Local development

The developer quickstart gets you running. This page covers the development environment in more detail.

Services and ports

pnpm dev runs every app with a dev script, plus Inngest and Drizzle Studio.

Environment files

Each app validates its own environment:

apps/admin/.env
apps/storefront/.env
packages/db/.env

Use the .env.example files as templates. The admin and storefront must share the same BETTER_AUTH_SECRET and DATABASE_URL.

Database workflow

pnpm db:dev:up      # start PostgreSQL
pnpm db:migrate     # apply committed migrations
pnpm -F admin db:seed

db:seed creates demo data and is intended for local development only. It requires Bun because the admin scripts run with Bun.

To inspect data, run pnpm db:studio or connect with any PostgreSQL client.

Running a single workspace

Turborepo filters:

pnpm dev:admin
pnpm dev:store
pnpm dev:docs
pnpm build:admin
pnpm build:store
pnpm build:sdk
pnpm check:admin
pnpm check:store

For an arbitrary workspace, use pnpm -F <workspace> <script>.

Inngest

The admin app serves the Inngest endpoint at /api/inngest. The local dev server is started by pnpm dev:admin on port 8310.

• Open the Inngest dev UI to inspect runs and replay events.
• If port 8288 is unavailable on Windows (Hyper-V/WSL), the repo defaults the dev server to 8310; keep INNGEST_DEV in sync if you override it.
• Background jobs that send email, SMS, or generate PDFs need the dev server running.

Email and storage

• Email: Mailpit captures all messages. Open http://localhost:8025 to read OTPs, invitations, and order confirmations.
• Storage: SeaweedFS is available locally; RustFS is an alternative. Only run one storage service at a time. Cloudinary is the default provider.

Useful reset commands:

pnpm mail:reset
pnpm storage:reset
pnpm db:dev:reset      # backs up first
pnpm db:dev:reset:force

Making a change

1. Create a focused branch.
2. Make the change in the smallest relevant workspace.
3. Add or update tests.
4. Run pnpm check and pnpm check-types.
5. Run the relevant test suite.
6. Update docs if behavior changed.
7. Commit with a descriptive message.

Debugging

• Env validation fails on startup: compare .env with .env.example; the error names the missing variable.
• Database connection refused: pnpm db:dev:up and check port 5432.
• Storefront shows no products: publish a product and verify ORGANIZATION_SLUG and API_KEY.
• Emails do not arrive: start Mailpit and check SMTP_* values.
• PDFs fail: check the Puppeteer runtime and storage credentials.
• Docs API pages are stale: run pnpm docs:sync-api.

Related

• Database
• Testing
• Troubleshooting