id: local-dev
type: guide
owner: justin
describes:
  - wrangler.jsonc
  - workers/*/wrangler.jsonc
  - scripts/seed.sql
reviewed: 2026-10-15

Running the shop locally

You need Node 24 and, for checkout, a Stripe account in test mode. Everything else runs in wrangler's local mode.

The API

npm install
npm run db:migrate          # applies migrations/ to the local D1
npm run db:seed             # six products, one of them out of stock
echo 'ADMIN_TOKEN=dev-admin-token' > .dev.vars
npm run dev                 # storefront-api on localhost:8787

curl localhost:8787/products lists all six; the candle is out of stock, so adding it to a cart fails. Checkout needs the payments Worker running too, with a Stripe test mode secret key.

Image URLs point at IMAGES_URL from wrangler.jsonc. Locally the upload works but the URL does not resolve, because the custom domain serves the production bucket ([[product-images]]). Set IMAGES_URL in .dev.vars to another origin if you want working links.

The other Workers

Each has its own config, so run it in a second terminal from the repository root:

npx wrangler dev -c workers/payments/wrangler.jsonc --port 8788
npx wrangler dev -c workers/fulfilment/wrangler.jsonc --port 8789

Each Worker reads its secrets from a .dev.vars next to its config: STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET for payments, WAREHOUSE_URL and WAREHOUSE_TOKEN for fulfilment. wrangler connects the service bindings between the running Workers (PAYMENTS one way, ORDERS the other), and the order-events queue between storefront-api and fulfilment. See [[payment-webhook]] for forwarding Stripe's test events and [[fulfilment]] for the warehouse settings.

Cron

The unpaid order expiry runs on a cron trigger. To run it once by hand:

npx wrangler dev --test-scheduled
curl 'localhost:8787/__scheduled?cron=*/5+*+*+*+*'

Tests

The tests need none of this; see [[testing]].