Starters · create-bsv-app

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.

Custom React / Express starter

--starter custom · You pick

Choose a frontend, backend, or both, then add BSV capabilities.

React wallet starter

--starter react · React

A Vite React app with wallet connection and optional authentication capabilities.

Express BSV API starter

--starter express · Express

A lean TypeScript Express API with optional BSV authentication capabilities.

Full-stack wallet starter

--starter full-stack · React + Express

Independent React and Express apps with one root command and an end-to-end wallet flow.

npx create-bsv-app@latest my-app --starter full-stack --yes

npx create-bsv-app@latest my-app --starter react --capabilities wallet-login --yes

npx create-bsv-app@latest my-api --starter express --capabilities signed-requests --yes

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 diveWhat "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 (opens in a new tab)
`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 (opens in a new tab)
`pollr`	React + Express · BRC-102	Pollr: Blockchain polls backed by overlay networks.	p2ppsr/Pollr (opens in a new tab)
`meter`	React + Express · BRC-102	Meter: An introduction to wallets, sCrypt contracts, and overlays.	p2ppsr/meter (opens in a new tab)
`metamarket`	React + Express · BRC-102	MetaMarket: A marketplace for 3D objects.	p2ppsr/MetaMarket (opens in a new tab)
`todo`	React · BRC-102	ToDo List: A simple demonstration of wallet baskets and encryption.	p2ppsr/todo-ts (opens in a new tab)
`marscast`	React	MarsCast: Micropayment-monetized weather data from Mars.	p2ppsr/mars-cast (opens in a new tab)
`coinflip`	React + Express · BRC-102	Coinflip: Trustless, provably fair peer-to-peer interactions.	p2ppsr/coinflip (opens in a new tab)
`postboard`	React + Express · BRC-102	Postboard: A public town square of messages built on an overlay.	p2ppsr/hello-overlay (opens in a new tab)
`locksmith`	React + Express · BRC-102	Locksmith: Lock coins with a message and unlock them through a wallet.	p2ppsr/locksmith (opens in a new tab)
`peerpay`	React · BRC-102	PeerPay: Peer-to-peer BSV payments backed by identity.	p2ppsr/peerpay (opens in a new tab)
`atfinder`	React	AtFinder: An alternative PeerPay interface using the same protocols.	p2ppsr/atfinder-ui (opens in a new tab)

Terminal

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

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:

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 (opens in a new tab). Open a pull request there. A repository starter only needs a public repo, a branch and a README that explains how to run it.