Setup

Get running in 10-15 minutes. This guide walks through cloning, configuring environment variables, running migrations, and verifying everything works. Prefer the shorter checklist? Jump to Quick setup.

Clone and install

Package manager
Code
git clone cursorcraft-lab/cursorcraft-boilerplate my-saas
cd my-saas
pnpm install
git remote remove origin
pnpm dev

Create environment file

Code
cp .env.example .env.local

Open .env.local and configure the required values below.

Site URL

Code
NEXT_PUBLIC_SITE_URL=http://localhost:3000

Used for SEO (sitemap, canonical URLs, OG images) and magic link emails.

Database (required)

You need a PostgreSQL database. Options:

Supabase (recommended):

  1. Create account at supabase.com
  2. Create a new project
  3. Go to Project Settings > Database > Connection string > URI
  4. Copy and replace [YOUR-PASSWORD] with your password

Neon:

  1. Create account at neon.tech
  2. Create a project and copy the connection string

Local Docker:

Code
docker run --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:16

Then use: postgres://postgres:postgres@localhost:5432/postgres

Code
DATABASE_URL=postgres://user:password@host:5432/database

Auth secret (required)

Generate a secret for signing tokens:

Code
openssl rand -base64 32
Code
AUTH_SECRET=<paste-generated-secret>

OAuth providers (optional)

Skip if using magic links only.

Google OAuth:

  1. Go to console.cloud.google.com/apis/credentials
  2. Create OAuth 2.0 credentials
  3. Add redirect URI: http://localhost:3000/api/auth/callback/google

GitHub OAuth:

  1. Go to github.com/settings/developers
  2. Create a new OAuth App
  3. Set callback URL: http://localhost:3000/api/auth/callback/github
Code
AUTH_GOOGLE_ID=xxx.apps.googleusercontent.com
AUTH_GOOGLE_SECRET=GOCSPX-xxx
AUTH_GITHUB_ID=Iv1.xxx
AUTH_GITHUB_SECRET=xxx

Email (optional to start)

Get API key from resend.com. Sandbox mode works for development.

Code
RESEND_API_KEY=re_xxx
EMAIL_FROM_ADDRESS=noreply@yourdomain.com
EMAIL_FROM_NAME=My App

Billing (optional to start)

Configure when ready to monetize. See Billing for details.

Run database migrations

Package manager
Code
pnpm db:migrate

Start development server

Package manager
Code
pnpm dev

Open http://localhost:3000

Verify setup

After setup, verify everything works:

  • Visit / - You see the home page
  • Visit /login - You see magic link form + OAuth buttons
  • Visit /app/dashboard - Dashboard (after sign-in)
  • Visit /app/billing - Billing page
  • Visit /app/dashboard/setup - Setup status

Common issues

"Invalid OAuth callback"

Check callback URLs match exactly (including port 3000)

"Database connection failed"

  • Verify DATABASE_URL format
  • Check database is running

"AUTH_SECRET missing"

  • Generate with openssl rand -base64 32
  • Add to .env.local

Next: Explore the Features or dive into Authentication