Installation

This guide takes you from a fresh clone to the app running at http://localhost:3000.

Prerequisites

Node.js 20.9 or later (Next.js 16 requires Node 20.9+). Use an LTS release.
pnpm — the project's package manager. Enable it with corepack enable or install it from pnpm.io.
PostgreSQL — a local or hosted database you can connect to. You only need a reachable DATABASE_URL.

Only a database is required to boot. Email, OAuth, payments, and AI each need their own keys, but the app starts without them — those features stay inactive until configured. See Environment Variables.

Setup

Install dependencies

pnpm install

Create your environment file

Copy the example and fill in at least DATABASE_URL and the Better Auth values:

cp .env.example .env

The minimum to boot locally:

DATABASE_URL — your PostgreSQL connection string.
BETTER_AUTH_SECRET — a random secret. Generate one with openssl rand -base64 32.
BETTER_AUTH_URL — http://localhost:3000 for local development.

Everything else is optional for a first run. See Environment Variables for the full reference.

Initialize the database schema

Push the Drizzle schema to your database:

pnpm exec drizzle-kit push

This creates the auth and payment tables. See Database for the schema and the production migration caveats.

Start the dev server

pnpm dev

Open http://localhost:3000.

Verify the installation

Work through this checklist to confirm each layer is wired:

Homepage loads at http://localhost:3000.
Database connects — no connection errors in the terminal, and drizzle-kit push completed without error.
Registration — create an account at /register.
Email verification — registration requires a verified email. Without Resend configured, the verification email won't send and login is blocked. See the note below.
Dashboard — after verifying and logging in, /dashboard is reachable.

Email verification is required by default (requireEmailVerification: true in src/lib/auth.ts). If RESEND_API_KEY is not set, the verification email cannot be delivered and the new account cannot log in. For local testing, configure Resend (Email) or temporarily relax this setting in src/lib/auth.ts.

Package scripts

These are the scripts defined in package.json:

Command	What it does
`pnpm dev`	Start the Next.js dev server
`pnpm build`	Production build
`pnpm start`	Serve the production build (after `build`)
`pnpm lint`	Run Biome checks (`biome check`)
`pnpm format`	Format with Biome (`biome format --write`)

Database commands

Drizzle Kit is invoked directly with pnpm exec; these are not package scripts:

Command	What it does
`pnpm exec drizzle-kit push`	Push the schema to the database (local workflow)
`pnpm exec drizzle-kit studio`	Open Drizzle Studio to browse data

Common first-run failures

Symptom	Likely cause	Fix
Connection refused / `ECONNREFUSED` on boot	`DATABASE_URL` missing or PostgreSQL not running	Start PostgreSQL and verify the URL
Auth errors / invalid session	`BETTER_AUTH_SECRET` missing or changed	Set a stable secret in `.env`
Can't log in after registering	Email verification required but Resend not configured	Configure `RESEND_API_KEY` or relax verification locally
OAuth buttons do nothing or error	GitHub/Google credentials not set	Configure the provider or hide its button — see Authentication