Skip to content
create-bsv-app

Reference

ProjectConfig reference

The JSON accepted by --file. Every field, its type, its default, and how it maps to the CLI flags.

--file <path> reads a complete config and skips the prompts. Every way into the CLI (flags, prompts, --ui) builds this same object, so this page is also the precise meaning of every flag.

config.json
{
  "mode": "new",
  "name": "my-app",
  "starter": "custom",
  "stack": {
    "frontend": { "framework": "react", "variant": "react-ts" },
    "backend": { "framework": "express" }
  },
  "targets": { "client": "client", "server": "server" },
  "bsvDir": "src/bsv",
  "capabilities": ["wallet-login", "signed-requests"],
  "glue": true,
  "install": true,
  "packageManager": "npm",
  "network": "test"
}
Terminal
npx create-bsv-app@latest --dir my-app --file config.json

Only name is always required. A new config also needs a stack, either from a named starter or from stack on custom.

Fields#

Field Type Default Flag
mode "new" | "add" "new" new / add, --mode
name string required --name
dir string "." --dir (the flag wins)
starter string "custom" --starter
stack.frontend { framework: "react", variant?: string } none --frontend, --variant
stack.backend { framework: "express" } none --backend
targets { client?: string, server?: string } from the stack none
bsvDir string "src/bsv" --bsv-dir
capabilities string[] [], plus wallet-connect in new --capabilities
glue boolean true --glue / --no-glue
install boolean true --install / --skip-install
packageManager "npm" | "pnpm" | "yarn" | "bun" "npm" --package-manager
network "main" | "test" | "ttn" "test" --network

mode#

"new" scaffolds into an empty directory. "add" installs capabilities into an existing project. Any value other than "add" is treated as "new". On the command line, --mode overrides the file.

name#

Passed to the generators, written to package.json and the manifest. Required in every mode.

starter#

Any id from the catalogue. With a named starter (react, express, full-stack or a complete example) in new mode, stack and targets come from the starter and your values are ignored. custom uses your stack.

stack#

frontend.framework must be "react" and backend.framework must be "express". Anything else is an error. variant is the create-vite template (default "react-ts"). Omit a side for none.

targets#

Where each app lives, relative to the project root. The defaults are client and server when there are both, and the root ("") when there's one. They must be safe relative paths: no absolute paths, no ... You'll mainly set these in add mode for unusual layouts.

bsvDir#

Where capability files go inside each target. Must be a safe relative path.

capabilities#

Ids from wallet-connect, wallet-login and signed-requests. In new mode, required capabilities are added for you and wallet-connect is always included. In add mode they're not expanded, so list wallet-connect yourself on a project that doesn't have it. Complete-example starters reject any capabilities.

glue#

When true, new mode edits the base app so everything runs immediately. When false, files are still written, and AGENTS.md prints the snippets to paste. Ignored in add mode, which never edits your files.

install#

Run the package manager's install in each app before exiting. In existing apps, a lockfile decides which package manager is used.

packageManager#

Used for create-vite, the install and the generated root runner script.

network#

The default baked into both config.ts files. VITE_BSV_NETWORK and BSV_NETWORK override it at runtime. See Networks.

Validation errors#

A bad field fails fast with Invalid config: …, for example targets.client must be a safe relative path, stack.frontend.framework must be "react", invalid bsvDir: … or name is required. File problems read config file not found: …, cannot read config file: … or invalid JSON in ….