# ProjectConfig reference

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

> Agents: search these docs with the `search_docs` tool on the MCP server at https://createbsvapp.vercel.app/mcp, or read everything at https://createbsvapp.vercel.app/llms-full.txt.

`--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.

```json [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"
}
```

```bash
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](https://createbsvapp.vercel.app/docs/starters). 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](https://createbsvapp.vercel.app/docs/add-to-existing#how-the-cli-finds-your-app) 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](https://createbsvapp.vercel.app/docs/bsv-primer#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 …`.