> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build an iCommerce Storefront

> Scaffold the 1.39 Next.js starter, check launch configuration, and verify a private native checkout journey.

The maintained `create-stateset-app` starter embeds iCommerce behind a Next.js storefront.
It includes catalog, carts, native orders/inventory and a USDC-on-Base checkout path.
The local commerce ledger is denominated in **USD**; token settlement is a separate rail.

## Scaffold and inspect

Use Node 20.20+ and npm 10+. From the source checkout you can inspect
`packages/create-stateset-app`; the published command is:

```bash theme={null}
npm create stateset-app@1.39.0 my-store
cd my-store
cp .env.example .env.local
npm run seed
npm run doctor
npm run verify:journey
npm run dev
```

The seed script honors Next environment files, activates new sample products and preserves
stock on repeated seeds. Existing catalog conflicts are errors to resolve, not permission
to reset operator stock. Use a disposable store during setup.

## Understand the checks

| Check | Scope |
| - | - |
| `doctor` | Local configuration and existing SQLite header; no migration/seed or provider acceptance |
| `doctor:launch` | Explicit tax/shipping, public HTTPS URL, HTTPS RPC, merchant address and persistent store |
| `verify:journey` | Private disposable native cart, reservation, checkout retry, partial refund and reopen test |
| `/api/store/status` | Limited availability/merchant/chain information checked before requesting transfer |

Journey verification simulates settlement, ignores the operator database path and transfers
no funds. A passing doctor cannot prove tax compliance, RPC reachability, database integrity,
or external settlement. Optional chat-provider credentials are separate from checkout readiness.

## Preserve exact checkout identity

The starter rounds line taxes to USD cents, rejects fractional-cent shipping and binds
checkout retries to the complete cart identity. Delayed retries preserve later order,
payment and refund state. The rail verifies the intended token, sender/recipient, amount,
confirmation and replay conditions; a transaction hash alone is not proof of acceptance.

Native merchant integrations require read-only buyer/cart authorization, operator-owned
kernel authority and authoritative original receipt lookup. Reference protocol SQLite
state is separate from native Commerce order state. A durable reference demo with simulated
balances is not a production payment endpoint.

Before launch, retain exact source/package/CI evidence, verify actual provider acceptance
and recovery, configure durable storage and key custody, and agree on operating limits.
See [governed execution](/stateset-icommerce/governed-execution) and
[backup/recovery](/stateset-icommerce/stateset-icommerce-backup-restore).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.