# Build your first app

> From an empty folder to an app running inside a Storeware shop, in five commands.

Source: https://storeware.ai/docs/get-started/quickstart

> **Early access.** The CLI and the SDK are not on npm yet, so the commands below do not run for everyone. To build an app now, write to https://storeware.ai/contact.

## Start one

```bash
npx @storeware/cli init my-app --template react-router
cd my-app
npm install
```

`init` writes a manifest, `storeware.app.toml`, and an app built on the [SDK](https://storeware.ai/docs/sdk), from one of four templates: `node` (plain JavaScript, the default), `typescript` (Hono), `react-router` or `nextjs`. The last two have a home inside the admin built with [App UI](https://storeware.ai/docs/extensions/app-ui) and [App Bridge for React](https://storeware.ai/docs/extensions/app-bridge-react). Each has an `AGENTS.md` for a [coding agent](https://storeware.ai/docs/cli/mcp). It overwrites nothing that already exists.

The app has the CLI as a development dependency, so in its folder `npx @storeware/cli` runs the version the app was made with.

## Sign in

```bash
npx @storeware/cli login
```

New to Storeware? `npx @storeware/cli login --signup` first makes a developer account: an organisation for your apps, your profile, and a development store with sample products and customers. No shop needed.

The CLI shows a code and opens the admin. Check the code matches, choose the organisation, and approve. No key is ever pasted into a terminal. The sign-in can do what your role allows, limited to building apps and to your development stores; it can never reach a shop that sells.

## Run it on a development store

```bash
npx @storeware/cli app dev -- npm run dev
```

`app dev` picks or makes a [development store](https://storeware.ai/docs/get-started/development-stores), opens a tunnel to your laptop (downloading Cloudflare's `cloudflared` the first time, and checking its checksum, unless you have it), sends your manifest with the tunnel's address in place of localhost, installs it, and starts your server with its credentials in the environment. Open the link it prints to see your app inside the admin. Every save of the manifest sends it again.

A development store never opens, and takes [test payments](https://storeware.ai/docs/get-started/test-payments) only, where no money moves. Give it something to work with:

```bash
npx @storeware/cli store seed
npx @storeware/cli store test-order --paid
```

## Take a test payment

```bash
npx @storeware/cli store test-order --pay approve
```

Your app receives `order.created.v1` and `order.paid.v1`. Try `--pay decline` and `--pay needs_action` too, or pay in the store's preview, where the checkout has a button for each ending. Refund the order from the admin to see `order.refunded.v1`.

## Hear an event

```bash
npx @storeware/cli webhook trigger order.paid.v1
```

This sends your app the latest real event of that topic from your development stores, signed exactly as a delivery is. See [Webhooks](https://storeware.ai/docs/webhooks) for what to do with it.

## Check it as a reviewer would

```bash
npx @storeware/cli app preflight
```

Runs the checks a review runs, against your app on the development store: every address is https, a signed delivery is accepted and a forged one refused, your home opens with a session, storefront blocks answer within 700 ms, and an app reading personal data says where privacy requests go. When your [listing](https://storeware.ai/docs/selling/listing) is written, `npx @storeware/cli app submit` sends it for review.

## Ship it

```bash
npx @storeware/cli app deploy
```

A deploy is a release: an immutable copy of your manifest. Shops already running your app move to it at once if it reaches no further than before; if it asks for more, each merchant approves it first. When it is ready for other shops, write its [listing](https://storeware.ai/docs/selling/listing) and publish it from the Developer page.