techtide-replit-fullstack-bootstrap

Replit Full-Stack Bootstrap

A Replit project without a written contract becomes an unmigratable snowflake. Define the contract first, prove the smallest loop, and plan the exit before you need it.

Workflow

1. Define the app contract. Runtime, package manager, app entrypoint, persistence layer, and the environment variable model split into public and private. Write it down before generating code.
2. Build the smallest vertical slice that runs in Replit and proves the app loop: one route, one write, one read back.
3. Add the safety floor before expanding. A health check endpoint, a smoke test that exercises the slice, and README commands for run and test.
4. Keep credentials in Replit secrets. Code and docs record variable names only, never values.
5. Plan the repo migration trigger. The moment the prototype needs CI, private deployment, custom infrastructure, or deep tests, it moves to a durable repository. Name that trigger in the README now. Read references/adapter-map.md when companion outputs for other harnesses are requested.

Output contract

Return a concise brief with:

• Bootstrap prompt.
• Env contract (names, public/private, purpose).
• Smoke test plan.
• Repo migration checklist with the named trigger.
• Verification performed and still required.
• Security and privacy notes.

Guardrails

• Never request or expose credentials, tokens, DSNs, service-role keys, customer data, or business exports.
• Placeholders for people, accounts, projects, URLs, and datasets unless the user supplies public-safe values.
• Explicit human approval before public deployment, billing changes, external messaging, or destructive actions.

Good vs bad

Good env contract line: DATABASE_URL | private | Postgres connection, set in Replit secrets, never printed.

Bad: a config.js with the connection string inline "because it's just a prototype". Replit projects get forked and shared; the prototype excuse leaks real credentials more often than production code does.

Verification

Do this: from a fresh Replit run, hit the health check and run the smoke test command from the README. Expect the health check to return OK and the smoke test to pass using only documented env variable names. If either fails, or setup required a step not in the README, the bootstrap is incomplete: fix the contract or the docs before adding features.

Completion checklist

• [ ] App contract written: runtime, package manager, entrypoint, persistence, env model
• [ ] Smallest vertical slice runs and proves the loop
• [ ] Health check, smoke test, and README commands exist
• [ ] Secrets in Replit secrets, names only in code and docs
• [ ] Migration trigger named in the README

Any box unchecked: not done. Fix or say so.

Footguns

• Expanding features before the smoke test exists: every later bug costs a manual re-test of everything. The safety floor is cheapest at step 3, unaffordable at step 30.
• Letting Replit's implicit magic (auto-detected run command, injected env) stand in for the contract: the project then only runs on Replit, which defeats the migration path. Make the contract explicit.
• Treating the migration checklist as optional paperwork: the trigger conditions (CI, private deploy, custom infra, deep tests) arrive suddenly. A project past its trigger that has not moved is accruing rework daily.