# Starters

> Every project starts from a starter. Pick a clean generated scaffold you compose with capabilities, or copy a complete example app.

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

Choose a starter with `--starter <id>`, or pick one from the list in the interactive prompts. There are two kinds, and they behave very differently:

| What | Generated starters | Complete examples |
| --- | --- | --- |
| What you get | A fresh Vite and/or Express app, plus BSV helper files | A full app, cloned from its GitHub repo |
| Takes capabilities | Yes | No. Passing any is an error |
| Runs with | `npm run dev` | whatever its README says |
| `AGENTS.md` | Yes | Only if the repo ships one |
| Needs `git` installed | No | Yes |

## Generated starters

Clean, minimal and wired. New projects always get `wallet-connect`. Add the others with `--capabilities`.

| Starter | Stack | What you get |
| --- | --- | --- |
| `custom` | You pick | Choose a frontend, backend, or both, then add BSV capabilities. |
| `react` | React | A Vite React app with wallet connection and optional authentication capabilities. |
| `express` | Express | A lean TypeScript Express API with optional BSV authentication capabilities. |
| `full-stack` | React + Express | Independent React and Express apps with one root command and an end-to-end wallet flow. |

::: code-group
```bash [full-stack]
npx create-bsv-app@latest my-app --starter full-stack --yes
```
```bash [react]
npx create-bsv-app@latest my-app --starter react --capabilities wallet-login --yes
```
```bash [express]
npx create-bsv-app@latest my-api --starter express --capabilities signed-requests --yes
```
```bash [custom]
npx create-bsv-app@latest my-app --starter custom --frontend react --backend express --yes
```
:::

### Which one?

- **`full-stack`**: start here. You get the complete wallet flow, including mobile QR pairing, which needs a server.
- **`react`**: the frontend only, at the project root. Desktop wallet connect works. Mobile pairing, login and signed requests need a server to talk to, so point `VITE_API_URL` at one.
- **`express`**: an API only, at the project root. Use it to add BSV verification to a backend whose frontend lives elsewhere.
- **`custom`**: choose the stack yourself with `--frontend` and `--backend`. With both it's the same layout as `full-stack`. With one, that app sits at the project root.

::: deep What "generated" means
The CLI runs the official generators, then layers BSV files on top. React comes from `create-vite` (template `react-ts`, ESLint enabled). The Express app is a lean TypeScript skeleton. On top of those it writes the capability files into `src/bsv/`, wires providers and routes into the base app (unless `--no-glue`), adds dependencies to each `package.json`, writes `AGENTS.md` and `bsv-scaffold.json`, and installs.
:::

## Complete examples

Full, maintained apps from the BSV ecosystem. The CLI clones the latest commit of the listed branch (`git clone --depth 1`), deletes `.git` so the project starts with no history, records the exact commit in `bsv-scaffold.json`, and installs dependencies.

| Starter | Stack | What it is | Source |
| --- | --- | --- | --- |
| `brc102-frontend` | React · BRC-102 | **BRC-102 frontend project template**: The established frontend project template with deployment-info.json support. | [p2ppsr/frontend-project-template](https://github.com/p2ppsr/frontend-project-template) |
| `brc102-backend` | Express · BRC-102 | **BRC-102 overlay backend template**: The established overlay-service backend template with deployment-info.json support. | [p2ppsr/backend-project-template](https://github.com/p2ppsr/backend-project-template) |
| `pollr` | React + Express · BRC-102 | **Pollr**: Blockchain polls backed by overlay networks. | [p2ppsr/Pollr](https://github.com/p2ppsr/Pollr) |
| `meter` | React + Express · BRC-102 | **Meter**: An introduction to wallets, sCrypt contracts, and overlays. | [p2ppsr/meter](https://github.com/p2ppsr/meter) |
| `metamarket` | React + Express · BRC-102 | **MetaMarket**: A marketplace for 3D objects. | [p2ppsr/MetaMarket](https://github.com/p2ppsr/MetaMarket) |
| `todo` | React · BRC-102 | **ToDo List**: A simple demonstration of wallet baskets and encryption. | [p2ppsr/todo-ts](https://github.com/p2ppsr/todo-ts) |
| `marscast` | React | **MarsCast**: Micropayment-monetized weather data from Mars. | [p2ppsr/mars-cast](https://github.com/p2ppsr/mars-cast) |
| `coinflip` | React + Express · BRC-102 | **Coinflip**: Trustless, provably fair peer-to-peer interactions. | [p2ppsr/coinflip](https://github.com/p2ppsr/coinflip) |
| `postboard` | React + Express · BRC-102 | **Postboard**: A public town square of messages built on an overlay. | [p2ppsr/hello-overlay](https://github.com/p2ppsr/hello-overlay) |
| `locksmith` | React + Express · BRC-102 | **Locksmith**: Lock coins with a message and unlock them through a wallet. | [p2ppsr/locksmith](https://github.com/p2ppsr/locksmith) |
| `peerpay` | React · BRC-102 | **PeerPay**: Peer-to-peer BSV payments backed by identity. | [p2ppsr/peerpay](https://github.com/p2ppsr/peerpay) |
| `atfinder` | React | **AtFinder**: An alternative PeerPay interface using the same protocols. | [p2ppsr/atfinder-ui](https://github.com/p2ppsr/atfinder-ui) |

```bash
npx create-bsv-app@latest my-meter-app --starter meter --yes
cd my-meter-app
# now follow the README that came with it
```

::: warning Examples ignore stack flags and reject capabilities
A complete example ships its own structure, so `--frontend`, `--backend` and `--variant` are ignored. `--capabilities` fails with `starter meter is a complete example and does not accept generated capabilities`. Want capabilities? Use a generated starter.
:::

::: note What's BRC-102?
Starters tagged **BRC-102** use a `deployment-info.json` file describing how the app and its overlay services are deployed. You only need it if you're using that deployment tooling. Read more in the [BSV primer](https://createbsvapp.vercel.app/docs/bsv-primer#brcs-you-will-meet).
:::

### Knowing exactly what you cloned

Because examples track a branch, two people cloning on different days can get different code. The manifest makes it reproducible:

```json [bsv-scaffold.json]
{
  "starter": {
    "id": "meter",
    "kind": "repository",
    "repository": "https://github.com/p2ppsr/meter.git",
    "ref": "master",
    "commit": "4f1c…"
  }
}
```

To get the same code later, check out that `commit` from that `repository`.

## Suggest a starter

Built something others should start from? Starters live in the CLI's catalogue in [`src/starters.ts`](https://github.com/bsv-blockchain/ts-stack/tree/main/packages/helpers/create-bsv-app). Open a pull request there. A repository starter only needs a public repo, a branch and a README that explains how to run it.