Why create-bsv-app

The problems#

Adding "log in with a wallet" to a web app sounds like one feature. Done properly, it's a dozen.

Connecting is a state machine, not a button. Users have a desktop wallet, a phone wallet or neither. Desktop needs a local probe; phone needs a relay server, a session, a QR code and a WebSocket. Every app reinvents this, and most only ship the happy path.

Signatures are easy; secure signatures are not. A proof must name which server it's for, what action it authorizes, which exact body it covers, when it expires, and be refused the second time it arrives. Miss one and you've built a replayable password. These are the bugs that never show up in a demo.

The boring parts are where the holes are. An API client that follows redirects can carry a proof to another host. A server that falls back to a random key in production changes identity on every deploy. A CORS rule mistaken for auth protects nothing. None of these are BSV problems, and all of them break BSV auth.

Then there's the glue. Providers in main.tsx, routes in App.tsx, CORS and the relay in the server, environment variables on both sides, and a README nobody keeps current.

The positions we take#

Generate code, don't wrap it in a library. The code that decides who's logged in is the code you most need to read, change and own. create-bsv-app writes small, plain TypeScript files into your project. No runtime package of ours sits in your dependency tree, and nothing is hidden. The cryptography itself comes from maintained packages (@bsv/sdk, @bsv/auth, @bsv/wallet-relay).

Identity comes from the wallet. No passwords, no emails, no reset flows. The user's identity key is the account, proven by a signature on every request that matters.

Fail closed. Proofs expire in two minutes and work once. The API client refuses redirects and caps sizes. Production config refuses to start without HTTPS and a stable key. When something's wrong, you get an error at deploy time instead of a breach later.

One pipeline, four ways in. Prompts, flags, a JSON file and a browser form all produce the same config and the same result. Humans and agents drive the same tool.

Working beats blank. npm run dev gives you a running app with a connected wallet, a login and a signed request, so you start from something that works and change it.

What it isn't#

• Not a wallet. Users bring their own BRC-100 wallet, such as BSV Browser (opens in a new tab).
• Not a framework. After scaffolding, it's out of the way. Re-run it only to add capabilities.
• Not (yet) payments. The scaffold covers identity and authentication. Transactions are your next step: see your first payment.
• Not a backend-as-a-service. No accounts, no hosted database, no lock-in. You deploy two ordinary apps.

Read next#