Installation

Clone the repository

git clone https://github.com/usenextbase/tanstack-planetscale-starter.git
cd tanstack-planetscale-starter

The repository keeps its older PlanetScale name. The database is Neon Postgres in production and plain PostgreSQL in Docker locally.

Enable pnpm through corepack

corepack enable
pnpm --version

The packageManager field pins pnpm 11.1.2. Corepack uses that version automatically. .npmrc sets engine-strict=true, so an older Node.js fails at install time.

Create the env file

[ -f .env ] || cp .env.example .env

Docker Compose reads .env for the published ports. The Node processes read process.env and fall back to defaults in apps/web/src/server/env.ts that match .env.example, so a first run works without changing anything. Nothing in the repository loads .env into the Node processes for you: when you change an application value such as BETTER_AUTH_SECRET, export it in the shell that runs pnpm dev or use an env loader of your choice. See environment variables for what each value does.

The admin app has its own small template at apps/admin/.env.example. Locally you can leave it alone; the defaults already point the admin at http://localhost:3001 and the web app at http://localhost:3000.

Install, start the services and prepare the database

pnpm setup

pnpm setup runs four steps in order: pnpm install, pnpm infra:start, pnpm db:migrate and pnpm db:seed.

• infra:start runs docker compose up -d --wait for postgres, pgbouncer, mailpit and minio.
• The Postgres container runs apps/database/docker/postgres-init.sql on first start, which creates the migration_owner, auth_runtime, app_runtime, worker_runtime and function_owner roles.
• db:migrate applies the SQL files in apps/database/migrations/ (0000_baseline through 0003_user_admin_mcp) through the direct connection (DATABASE_DIRECT_URL) and records a SHA-256 checksum for each one in public.nextbase_migrations. Editing an already applied migration is a hard failure.
• db:seed creates an admin@nextbase.local user with the admin role, the acme workspace (Acme Inc.) owned by that user and a Launch project.

Start the web and admin servers

pnpm dev

pnpm dev runs turbo run dev --parallel, which starts every workspace package that has a dev script: the web server (tsx watch server.ts in apps/web, port 3000), the admin server (PORT=3001 tsx watch server.ts in apps/admin) and the React Email preview server from apps/email.

Open these addresses:

Start the outbox worker

Verification and password reset emails are written to app.outbox_jobs and sent by a separate process. Without it, no email reaches Mailpit. In another terminal:

pnpm --filter @nextbase/web worker

This runs tsx watch worker.ts with NEXTBASE_WORKER_MODE=daemon and polls the outbox as the worker_runtime role. Keep it running while you develop.

Create your account and workspace

Open http://localhost:3000/sign-up, enter a name, email and a password of at least 8 characters. Email verification is required, so open Mailpit at http://localhost:38025, open the verification mail and follow the link. The kit signs you in after verification and sends you to /app.

Open Workspaces and create one. The form posts to /api/v1/workspaces, which creates the workspace, makes you its owner and records a workspace.created audit event inside an actor transaction. The overview page then lists it.

Grant yourself application admin

pnpm admin:grant -- you@example.com

This runs apps/database/src/grant-admin.ts, which sets role = 'admin' on your Better Auth user through the direct connection and fails if the email doesn't exist. Sign out and back in, then open http://localhost:3001/login, sign in with the same email and password, and you land on /app-admin. See authentication for what the role controls.

Check that everything works

pnpm db:check          # roles, forced RLS and function grants
pnpm verify            # format check, lint, typecheck, unit tests, production build
pnpm test:integration  # PostgreSQL, RLS and impersonation tests through PgBouncer

pnpm verify is what CI runs. The integration suites in apps/database, apps/web and apps/admin need the Docker services running and the migrations applied; they refuse to run against a database that isn't on localhost. TESTING.md in the repository has the test policy.