DocsCLI
Open documentation actions
Add and Remove Capabilities
Add typed tooling, deployment targets, and stack capabilities to an existing project, or remove one under review.
add updates an existing Better Fullstack project. It reads bts.jsonc, plans the requested change, writes safe generated-file updates, and records the new selection.
npm create better-fullstack@latest add -- --email resend --dry-runOperational contract
| Concern | Contract |
|---|---|
| Preconditions | Run inside a generated project with bts.jsonc, or pass --project-dir. Commit or stash local work first. |
| Preview | add [flags] --dry-run plans without writing. |
| Writes | Updates scaffold-owned files, dependencies, env examples, bts.jsonc, and the manifest. |
| Refuses | Never overwrites a generated file that diverged from its recorded baseline. |
| Recovery | Review the dry run, apply on a clean Git worktree, revert the commit if needed. |
What add does
- Prompts in tooling and capability sections when no explicit stack flags are passed.
- Accepts additive flags such as
--email resend,--observability sentry,--search,--vector-db,--file-storage,--web-deploy, and--server-deploy. - Accepts
--part role:ecosystem:toolspecs for anything part-addressable. - Uses the same planning engine as the MCP stack-update tools.
- Skips capabilities already selected and refuses capabilities whose setup is imperative rather than generated.
- Prints install guidance when dependency installation is skipped.
Most create-time stack fields are accepted for existing projects when the planner can apply them safely. Risky architecture swaps require manual review or a fresh scaffold.
Flags
| Flag | Behavior |
|---|---|
--part | One or more canonical role:ecosystem:tool specs; owner-scoped parts use owner.role:ecosystem:tool. |
--dry-run | Plan the update and print the summary without writing files. |
--project-dir | Path to the generated project. Defaults to the current directory. |
--install | Install dependencies after adding files. Defaults to false; the lockfile stays outside the transaction, so re-run install after recovery. |
--package-manager | npm pnpm bun yarn |
--email --observability | Add providers such as resend or sentry when compatible with the stack. |
--search --vector-db --file-storage | Add supported service integrations. |
--web-deploy --server-deploy | Add or update deployment targets. |
Commonly added parts include turborepo, docker-compose, eslint, prettier, pwa, electron, capacitor, msw, storybook, and the TanStack data utilities. Vite+ is a toolchain profile selected as toolchain:universal:vite-plus; the package-manager flag still chooses npm, pnpm, Yarn, or Bun underneath it.
Recommended workflow
- Commit or stash current work.
- Run
add --dry-runwith explicit flags. - Review the file, dependency, env, and manual-review summary.
- Re-run without
--dry-run. - Install dependencies if the command skipped it.
- Run
check --skip-checks, then the project's own tests.
If every requested capability is already present, add reports that there are no stack changes to apply.
Remove a capability
remove takes one selected non-primary capability back out. It plans by default, names the affected config fields and generated files, and returns a review token. Nothing is written during planning:
npx create-better-fullstack@latest remove backend.auth:typescript:better-authAfter reviewing, repeat the same target with --apply --review-token <token>. The token binds to the proposed config and file operations; missing or stale tokens fail closed. Apply uses the same transaction and recovery contract as update.
Primary frontend, backend, mobile, and database roles cannot be removed; replace those choices through add so compatibility and migration risks get reviewed. Architecture-sensitive removals additionally require --acknowledge-architecture-change. Application data and schemas are never migrated automatically.