Project Lifecycle

Better Fullstack records a generated project's selected stack in bts.jsonc and its comparison baseline in bts.lock.json. Those files help later commands classify current-template changes and local edits. Manifest v2 records CLI, generator, template-set, and schema provenance plus lifecycle history. Valid v1 manifests migrate deterministically without inventing original provenance.

Lifecycle at a glance

1. Create

Preview first when the stack is new or scripted:

npm create better-fullstack@latest my-app -- --dry-run

Remove --dry-run to scaffold. Commit the generated bts.jsonc and bts.lock.json; both are part of the project's reproducible history.

Choose the workspace layout during creation. monorepo is the default. single-app is restricted to thin Next.js and TanStack Start self-backend stacks that do not emit sibling database, auth, API, service, native, container, or deployment packages; later lifecycle commands preserve the recorded layout rather than converting an established project in place.

2. Evolve the selected stack

Use add when the desired configuration changes, for example, adding email, observability, an capability, or a deploy target. Plan the change before writing:

npm create better-fullstack@latest add -- --email resend --dry-run

Commit or stash local work first. The planner refuses to overwrite edited generated files and reports any manual-review blockers.

Use remove for one exact selected non-primary stack part. It plans by default and requires the same target plus its review token for transactional apply. Replace primary frontend, backend, mobile, or database choices through add so compatibility and migration checks can run.

3. Refresh templates

Use update when the stack selection stays the same but newer Better Fullstack templates exist. The default invocation is already a dry run:

npm create better-fullstack@latest update

Review the categorized plan and its token, then run the exact emitted apply command:

npm create better-fullstack@[same-cli-version] update [project-directory] -- --apply --review-token [64-character-token]

Use the exact version-pinned command emitted by the plan. On Windows the CLI labels and quotes it for PowerShell; on other supported platforms it emits POSIX-shell quoting.

Local edits, secrets, removed files, and conflicts are not selected for automatic writes. Apply rolls failed writes back and emits a recovery command for successful transactions. Migrated or manually adopted manifests require the additional lineage acknowledgement shown by their plan.

4. Generate inside the project

gen is a narrow, experimental in-project generator. Today it can preview and create TypeScript tRPC/oRPC resource routers:

npm create better-fullstack@latest gen resource post -- --dry-run

5. Diagnose and verify

Run check after creation, additions, updates, dependency installs, and environment changes:

npm create better-fullstack@latest check

Normal output runs the deterministic target matrix, including supported native ecosystem checks. JSON mode reports status without running those checks unless you explicitly pass --run-checks:

npm create better-fullstack@latest check -- --json --run-checks

With --run-checks, JSON changes presentation and captures subprocess output; it does not make those commands read-only. Missing targets, toolchains, or incomplete execution fail the command.

Recovery rule

Before any write to an established project, commit or stash your work, run the matching plan/dry run, and inspect blockers. If a requested architecture change includes a database, ORM, auth, API, backend, or runtime replacement, plan application-data and schema migrations separately.

Continue with Add and Remove Capabilities, Update and Check Projects, or a complete stack guide.