Getting Started

Prerequisites

Before you begin, make sure you have:

• Node.js 22+ (or use nvm with the repo's .nvmrc)
• pnpm (npm install -g pnpm)
• Docker (with the daemon running) — required for the local PostgreSQL container managed by Docker Compose

Install dependencies

pnpm install

Local evaluation (fastest path)

This path boots the app locally without connecting any external providers. Authentication, the dashboard shell, and the AI tools all work via the local PostgreSQL container and seeded test credentials.

1. Run setup

pnpm run setup

This command will:

• Check prerequisites (Docker, pnpm) and give guided recovery output if anything is missing
• Start the local PostgreSQL container via Docker Compose (port 54322)
• Apply Prisma migrations and seed the database with a preview user
• Create apps/web/.env.local from the example file if it does not exist
• Auto-populate the boot-critical environment variables so you do not need to hunt for values

2. Start the app

pnpm dev

The app will be available at http://localhost:3500.

3. Sign in with the preview user

4. Run the smoke check (optional)

For a repeatable, automated proof that the local path is working:

pnpm local-eval:smoke

This reruns setup, verifies the seeded user exists in Postgres, starts the app, and checks that both / and /auth/login respond as expected.

Environment variables

After running setup, apps/web/.env.local will contain the boot-critical local defaults. The following additional variables unlock provider-gated features:

Authentication

Email

Set exactly one of these sets to enable transactional email:

Payments

Set one of these to enable billing, subscriptions, and credit purchases:

File storage

AI tools

Analytics

Monitoring

Full integrated setup (Vercel + external providers)

For a fully wired environment with real auth, email, payments, and storage:

1. Create a Vercel project and link it to your repository.
2. Provision a Neon Postgres database (or any managed Postgres provider) and add DATABASE_URL and DATABASE_URL_UNPOOLED to your Vercel environment variables.
3. Add the provider variables listed above to Vercel (Settings → Environment Variables).
4. Push to your branch — Vercel will build and deploy automatically.
5. Run pnpm --filter @repo/database migrate after each schema change to keep the database in sync.

Parallel development with worktrees

If you work across multiple features in parallel, the repo includes worktree helpers:

# Create a new worktree for a feature branch
pnpm worktree:create

# Resume an existing worktree
pnpm worktree:resume

# List all active worktrees
pnpm worktree:list

# Remove a worktree when done
pnpm worktree:remove

Each worktree gets its own .env.local and a unique dev-server port so branches do not interfere with each other. The PostgreSQL container is shared across worktrees on port 54322.