Skip to content

Local Deployment

Purpose

Run any app or the API Worker against Cloudflare's local emulation - no production credentials needed.

Architecture/context

wrangler dev emulates Workers, D1 (SQLite-backed), and R2 locally. Nothing here touches the real Cloudflare account.

Prerequisites

See Local Development → Prerequisites - Node 22, npm, repo cloned, npm install run once at the root.

Files involved

  • Each app's own wrangler.jsonc (apps/*/wrangler.jsonc)
  • workers/api/wrangler.jsonc
  • workers/api/migrations/*.sql

Configuration

No secrets required for local dev - wrangler dev uses local D1/R2 emulation by default, not the remote resources. .env.example's VITE_API_BASE_URL is unreferenced in current app source, so no local .env is required to run any app - see Architecture → Applications.

Commands

# Apply migrations to the local D1 emulator (once, or after pulling new migrations)   [SAFE LOCAL]
npx wrangler d1 migrations apply akshaya-group-global --local --config workers/api/wrangler.jsonc

# Run the API Worker locally                                                          [SAFE LOCAL]
npm run dev:api

# Run any app locally (in another terminal)                                            [SAFE LOCAL]
npm run dev:corporate
npm run dev:software
npm run dev:logistics
npm run dev:commerce
npm run dev:embroidery
npm run dev:admin
npm run dev:investors

Step-by-step execution

  1. npm install at the repo root (once, or after a package.json change).
  2. Apply local migrations (command above) - required before the API Worker can serve any DB-backed route.
  3. Start npm run dev:api in one terminal.
  4. Start the app(s) you're working on in separate terminals.
  5. For an app whose own Worker also binds D1/R2 (Corporate, Software, Admin - see Architecture → Data Platform), its wrangler dev instance uses its own local D1/R2 emulation, separate from the API Worker's - local emulation is per-process, not shared, unlike production where the binding points at the same remote database/bucket.

Validation

Each npm run dev:* command prints a local URL (typically http://localhost:<port>) once ready. Confirm the API Worker responds: 

curl http://localhost:<api-port>/api/health        # [SAFE LOCAL]

Expected result

The app loads in a browser at its local URL; API-backed pages return real (locally-seeded, likely empty) data rather than network errors.

Troubleshooting

See Local Development → Troubleshooting.

Rollback/recovery

Nothing to roll back - local state lives only in .wrangler/ (gitignored). Delete it and re-apply migrations to reset: 

rm -rf .wrangler                                                                       # [SAFE LOCAL]

Security considerations

None - no production credentials are used for local dev.