Build your first app

Start oneCopy Anchor Link

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, 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 and App Bridge for React. Each has an AGENTS.md for a coding agent. 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 inCopy Anchor Link

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 storeCopy Anchor Link

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

app dev picks or makes a development store, 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 only, where no money moves. Give it something to work with:

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

Take a test paymentCopy Anchor Link

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 eventCopy Anchor Link

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 for what to do with it.

Check it as a reviewer wouldCopy Anchor Link

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 is written, npx @storeware/cli app submit sends it for review.

Ship itCopy Anchor Link

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 and publish it from the Developer page.