# Quick start

> Go from an empty folder to a running BSV app with a connected wallet, passwordless login and signed API calls.

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

One command gives you a React client, an Express server, a Connect wallet button and two working demos, with providers, routes and CORS already wired. You won't write any key-handling or transaction code to get there.

::: tip TL;DR
Install [BSV Browser](https://browser.bsvb.tech/), then:

```bash
npx create-bsv-app@latest my-app \
  --starter full-stack \
  --capabilities wallet-login,signed-requests --yes
cd my-app && npm run dev
```

Open http://localhost:5173 and click **Connect wallet**. The rest of this page explains each step.
:::

## Before you start

You need two things:

- **Node.js 22 or newer.** Run `node -v` to check. Older versions are unsupported and may fail in odd ways.
- **A BRC-100 wallet.** We recommend [BSV Browser](https://browser.bsvb.tech/). It's free and runs on macOS, Windows, iOS and Android. It holds your keys, so your app never does.

::: tip Nothing here costs money
Logging in and signing requests are *signatures*, not transactions. No coins move, and new projects target testnet by default.
:::

## Create your app

::::: steps

### Scaffold the project

Pick your package manager:

::: code-group
```bash [npm]
npx create-bsv-app@latest my-app \
  --starter full-stack \
  --capabilities wallet-login,signed-requests \
  --yes
```
```bash [pnpm]
pnpm create bsv-app my-app \
  --starter full-stack \
  --capabilities wallet-login,signed-requests \
  --package-manager pnpm --yes
```
```bash [yarn]
yarn create bsv-app my-app \
  --starter full-stack \
  --capabilities wallet-login,signed-requests \
  --package-manager yarn --yes
```
```bash [bun]
bun create bsv-app my-app \
  --starter full-stack \
  --capabilities wallet-login,signed-requests \
  --package-manager bun --yes
```
:::

That's a React + Express app with all three [capabilities](https://createbsvapp.vercel.app/docs/capabilities). `wallet-connect` is always included. `--yes` skips the prompts, and dependencies install before the command exits.

::: warning Using pnpm, yarn or bun? Pass `--package-manager`
The CLI doesn't detect which package manager launched it. Without the flag it installs with npm, whatever command you ran.
:::

### Start both apps

```bash
cd my-app
npm run dev
```

The root `dev` script starts the Vite client on **http://localhost:5173** and the Express server on **http://localhost:3000** together. Press <kbd>Ctrl</kbd> + <kbd>C</kbd> once to stop both.

### Connect your wallet

Open **http://localhost:5173**. You'll see *BSV app* and a **Connect wallet** button.

- **Desktop wallet open?** Approve the request in BSV Browser. The page switches to `Connected: 02ab…`. That hex string is your identity key.
- **No desktop wallet found?** A dialog offers **Connect with a mobile wallet**. Scan the QR code with BSV Browser on your phone and you're paired.

### Try the demos

Once you're connected, a **Demos** list appears:

- **Wallet login →** signs a `login` proof and sends it to `POST /api/login`. The server verifies it and replies with your identity key.
- **Signed request demo →** signs a single API call to `POST /api/echo`, bound to its exact body.

Both pages log every step, so you can watch the full exchange between wallet, client and server.

:::::

::: tip It worked if…
You see `✓ Logged in as 02…` on the login page. If you don't, check [Troubleshooting](https://createbsvapp.vercel.app/docs/troubleshooting#wallet).
:::

## Other ways to start

**Answer prompts instead of passing flags.** Run the command with no arguments and the CLI asks for the mode, starter, name, stack, capabilities, package manager and network:

```bash
npx create-bsv-app@latest
```

::: warning The `custom` starter needs a stack
`custom` is the default starter, and it defaults to no frontend and no backend. Choose at least one, or pick `full-stack`. Otherwise the CLI stops with `Invalid config: a new project needs at least a frontend or a backend`.
:::

**Use a form in your browser.** `--ui` opens a local, single-use configurator on `127.0.0.1` that walks through the same questions:

```bash
npx create-bsv-app@latest --ui --dir my-app
```

**Copy a finished example app.** Clone one of the [complete examples](https://createbsvapp.vercel.app/docs/starters#complete-examples) and read its README:

```bash
npx create-bsv-app@latest my-meter-app --starter meter --yes
```

::: note You'll see two sets of "next steps". Follow the last one
Halfway through, create-vite prints its own *Done. Now run: cd client / npm install / npm run dev*. Ignore it. The final **Next:** block is the one written for your project.
:::

## Where to next

::: cards
[**Try it in your browser** The interactive tutorial: edit the real scaffold, log in, sign a request, break it. Nothing to install.](https://createbsvapp.vercel.app/learn/welcome)

[**Build your first feature** A 15-minute tutorial: a guestbook where every entry is signed by a wallet.](https://createbsvapp.vercel.app/docs/tutorial)

[**Tour the project** Every generated file, and which ones you should edit.](https://createbsvapp.vercel.app/docs/project-structure)

[**BSV for web devs** Wallets, identity keys and BRCs in plain English.](https://createbsvapp.vercel.app/docs/bsv-primer)

[**Ship it** The three environment variables production needs, and why.](https://createbsvapp.vercel.app/docs/deploy)
:::