CLI: Local Development

This chapter covers how to bring up the local development environment using the command line only.

1. Install dependencies

From the repository root:

pnpm install

2. Run local D1 migrations

Each backend service that uses D1 needs its local database schema. Run migrations for each service:

cd backend/node1-auth-service && npx wrangler d1 migrations apply zship-auth --local && cd ../..
cd backend/node2-support-service && npx wrangler d1 migrations apply zship-support --local && cd ../..
cd backend/node3-pay-service && npx wrangler d1 migrations apply zship-pay --local && cd ../..
cd backend/node4-notify-service && npx wrangler d1 migrations apply zship-notify --local && cd ../..
cd backend/node5-blog-service && npx wrangler d1 migrations apply zship-blog --local && cd ../..
cd backend/node7-site-service && npx wrangler d1 migrations apply zship-site --local && cd ../..
cd backend/node8-prompt-service && npx wrangler d1 migrations apply zship-prompt --local && cd ../..
cd backend/node9-checkin-service && npx wrangler d1 migrations apply zship-checkin --local && cd ../..
cd backend/node10-ai-service && npx wrangler d1 migrations apply zship-ai --local && cd ../..

Or use the per-service scripts if available:

pnpm db:migrate:local
pnpm db:migrate:support:local
# ... repeat for each service with D1

3. Start backend Workers

Open separate terminals for each backend service, or use a process manager. From the repository root:

# Terminal 1 - Auth (port 8787)
cd backend/node1-auth-service && npx wrangler dev

# Terminal 2 - Support (port 8788)
cd backend/node2-support-service && npx wrangler dev --port 8788

# Terminal 3 - Pay
cd backend/node3-pay-service && npx wrangler dev --port 8789

# ... and so on for node4 through node10

Or use root scripts:

pnpm dev:auth      # node1-auth
pnpm dev:support   # node2-support
# etc.

4. Start frontend apps

In separate terminals:

# Terminal - Web (port 4321)
pnpm dev:web

# Terminal - Admin (port 4322)
pnpm dev:admin

For apps/web, create apps/web/.env using the same variable names as production — e.g. AUTH_SERVICE_URL, APP_KEY, BLOG_API_URL (see Bind domains and environment variables for the usual set). The app reads these via import.meta.env; site.ts holds typed defaults and presentation config, while env overrides wherever the code uses import.meta.env.* with a fallback.

5. Verify

• Web: http://localhost:4321
• Admin: http://localhost:4322
• Auth: http://localhost:8787

6. Checklist

• Dependencies installed
• All D1 migrations applied locally
• Backend Workers running
• Frontend apps running
• Can access web and admin in browser