Quick Start

Start with a fresh Supabase or Neon PostgreSQL database and choose Supabase Auth or Better Auth independently. The local foundation guide walks through credentials, sign-in and troubleshooting; Automatic Setup is the complete wizard reference.

1. Install dependencies

Clone the repository and activate Node 24.18.1 from .nvmrc before installing. With nvm on macOS/Linux, run nvm install and nvm use in the repository. With nvm-windows, run nvm install 24.18.1 and nvm use 24.18.1.

git clone <your-boilerplate-repo-url> my-saas
cd my-saas
# Activate Node 24.18.1 here, then:
node --version
corepack enable
pnpm --version
pnpm install --frozen-lockfile
pnpm run db:client:generate

The version checks must print v24.18.1 and 11.20.0. Corepack must be available in your Node installation; the repository's packageManager field selects pnpm. Keep the committed lockfile. The explicit generation step refreshes both application and Better Auth Prisma clients from the repository schemas.

2. Initialize the project

pnpm run init

Choose Simple for a first local installation. Use http://localhost:3777 as the application URL, enter your administrator email, and supply matching direct and pooled owner URLs for the fresh database. Init derives and attests separate application credentials; owner URLs never go into .env.local. For Better Auth, accept or supply a signing secret and keep its URL on the same origin as the application. For Supabase Auth or Storage, supply the project URL, publishable key and server-only secret key.

Simple mode defers payment credentials, AI keys and real email delivery. Advanced exposes optional services and infrastructure tuning. Follow the scheduler and rate-limit prompts; PostgreSQL pg_cron also requires an application worker. Review the configuration before installation. Type :back to revisit a section. Keep automatic database reset disabled for a normal fresh installation.

Init creates .env.local and config/app.ts, generates config/workspace.ts for B2B, and updates the default currency in config/pricing.ts. It backs up existing managed files and preserves custom environment keys. Do not overwrite the generated .env.local with .env.example afterward.

3. Start and check the application

pnpm run dev

Open localhost:3777 and check /api/health. A database health response is HTTP 200 with {"status":"ok"}; it does not verify email, payments or scheduling. Restart Next.js after changing environment variables.

When JOB_SCHEDULER_PROVIDER=postgres_pg_cron, run this in a second terminal:

pnpm jobs:worker

Include web and worker processes in the connection budget. For Neon's native scheduler, init reserves at least three application instances because the generated Docker Compose profile runs the web process plus separate critical and background workers. Confirm the backend limit against your provider tier.

Simple mode uses EMAIL_PROVIDER=noop, which sends no email and logs no usable sign-in link. Configure Brevo or Mailjet before testing sign-in through an inbox. For automated Auth checks without an email service, use the disposable local QA runner below. See Wire up the essentials for registration, administrator access, test checkout and AI setup.

4. Verify and prepare for release

# Requires a running Docker engine; owns a separate disposable local target.
pnpm run qa:local:gate

This checks the local supabase:supabase reference, not the hosted database configured by init. Other provider combinations have their own QA profiles.

Runtime startup checks supported providers and valid configuration independently of release evidence. Before publishing a release, run pnpm run qa:release and resolve its certification blockers. A successful init, development server or Docker build does not certify a release. Do not change compatibility evidence or activation fields to bypass that gate.