Developer quickstart

This tutorial gets the full monorepo running locally: database, admin dashboard, and storefront. Plan for about ten minutes on a machine that already has Docker.

Before you start

You need:

• Node.js 24 — the version in .node-version is 24.18.0.
• pnpm 12 — the repository uses packageManager: pnpm@12.14.0.
• Docker Desktop — used for PostgreSQL, Mailpit, and optional object storage.
• Bun — some admin scripts, including the database seed and feature flag CLI, run with Bun.

1. Install dependencies

pnpm install

2. Create the environment files

Each Next.js app validates its environment at startup, and Drizzle reads its own file from packages/db:

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

The example values work for local development with the Docker services. Keep BETTER_AUTH_SECRET identical in the admin and storefront files.

See Environment variables for the full list and the optional integrations.

3. Start PostgreSQL and apply migrations

pnpm db:dev:up
pnpm db:migrate

pnpm db:migrate applies the committed migrations from packages/db/migrations. For quick local schema syncing you can use pnpm db:push, but never run it against production.

Optionally seed demo data:

pnpm -F admin db:seed

4. Start the apps

Start the admin dashboard with its background worker and database studio:

pnpm dev:admin

Or start the storefront:

pnpm dev:store

To run everything, including this docs site, use:

pnpm dev

5. Connect the storefront to a store

The storefront is a separate app that talks to the admin API. It needs two values in apps/storefront/.env:

1. ORGANIZATION_SLUG — the store slug.
2. API_KEY — an API key created in the admin under Settings → API.

Create a store in the admin, create an API key, copy it once, and restart the storefront. If the store has no published products, the storefront will look empty.

6. Verify your setup

• Open the admin and sign in.
• Open the setup page for your store and complete the launch checklist.
• Open the storefront and confirm that a published product appears.

If the storefront shows an error, check the admin API URL (NEXT_PUBLIC_API_URL), the store slug, and the API key.

Useful commands

Next steps

• Read the architecture overview.
• Learn the database workflow.
• Set up testing before your first change.