Getting Started

Quick Start

SaaSProKit is a production-grade Next.js 16 monorepo using pnpm workspaces and Turborepo. Follow these steps to get the project running locally.

Prerequisites

Ensure you have the following installed:

• Node.js 22+ (required, see engines in root package.json)
• pnpm 10+ (project pins pnpm@10.19.0 via packageManager)
• Git
• PostgreSQL 12+ (or use Docker Compose — see below)
• macOS, Linux, or Windows (WSL2 recommended)

Installation Steps

1. Clone the repository

   git clone <repository-url>
   cd saasprokit

2. Install dependencies

   pnpm install

3. Set up environment variables

   Recommended: run the interactive setup CLI. It asks for your project name and deploy target (Cloudflare Workers / Vercel / Docker), then generates both apps/web/.env.local and packages/database/.env for you and removes the other hosts' configuration:

   pnpm run setup

   Setup rewrites this clone in place and cannot be re-run. Three deletions happen without a prompt: the deploy configs for the hosts you did not pick; this documentation tree (docs/, workspace package kit-docs, and the kit-docs:* scripts / --filter=!kit-docs guards); and — unless you pass --keep-setup — the CLI's own tooling (scripts/, dist/, tsup.config.ts, vitest.config.mts). Run it on a clean checkout, and pass flags if you want to keep any of it:

   Flag	Effect
   --keep-setup	Keep the CLI so you can run setup again
   --keep-all-hosts	Keep every host's deploy config
   --no-install	Skip pnpm install and the Prisma client build
   --no-commit	Skip the git commit step
   --yes	Skip confirmations (dirty-tree warning, env overwrite, commit). Still asks for project name and deploy target unless you also pass --name and --host
   --name <name>	Project name (required to skip the name prompt)
   --host <host>	Deploy target: cloudflare | vercel | docker

   The interactive run asks before committing. --yes does not — it commits straight away on a clean tree, and on a dirty tree it skips the commit rather than sweeping your uncommitted work into it. docs/ is always removed; there is no flag to keep kit-docs.

   --yes alone is not unattended. For a no-prompt run:

   pnpm run setup --yes --name acme --host cloudflare

   Do not copy the .env.example files by hand — pnpm run setup writes both apps/web/.env.local and packages/database/.env from the same DATABASE_URL. The database example ships with an empty URL. Prisma CLI commands (migrate, studio, db:seed) load packages/database/.env, not the Next.js app env.

   Families in apps/web/.env.example (edit the files setup wrote if you need to fill optional keys later):

   Family	Vars
   App (required)	NEXT_PUBLIC_APP_URL, NEXT_PUBLIC_APP_NAME, NEXT_PUBLIC_DOCS_URL
   Database	DATABASE_URL (default matches Docker postgres). Optional DIRECT_URL when using a pooled Neon URL
   Better Auth	BETTER_AUTH_SECRET, BETTER_AUTH_URL, BETTER_AUTH_TRUSTED_ORIGINS. Optional ADMIN_EMAILS for first-admin bootstrap
   OAuth (optional)	GOOGLE_CLIENT_ID / _SECRET, GITHUB_CLIENT_ID / _SECRET
   Stripe (optional in dev)	STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_{PRO,ENTERPRISE}_PRICE_ID_{MONTHLY,ANNUAL}
   Email	EMAIL_FROM, RESEND_API_KEY (prod), SMTP_* (dev defaults to MailDev on localhost:1025)
   Storage	STORAGE_PROVIDER (local / s3) plus local path / S3 (AWS_*) vars

4. Start local infrastructure

   pnpm dev does not start Postgres or MailDev.

   docker compose up -d postgres maildev

   Postgres is on 5432. MailDev SMTP is 1025; caught mail is at http://localhost:1080.

5. Set up the database

   pnpm migrate

6. Seed the database (optional, destructive)

   pnpm --filter @repo/database db:seed

   This wipes tables first (except RateLimit), then creates sample users (including admin@example.com / Password@saaspro), organizations, memberships, and subscriptions. It exits without running if NODE_ENV=production. See Database Design for what is seeded.

7. Run the development server

   pnpm dev

   This is turbo dev --filter=!kit-docs. It starts the customer apps, not this documentation site:

   • Main app: http://localhost:3000
   • Customer docs (apps/docs, empty Fumadocs starter): http://localhost:3004
   • Email preview: http://localhost:3003
   • Storybook: http://localhost:6006
   • Prisma Studio: http://localhost:3005

   SaaSProKit's own docs (this site, workspace package kit-docs) run separately:

   pnpm kit-docs:dev    # http://localhost:3006

   After pnpm run setup, root docs/ is deleted and kit-docs:dev is gone. Product docs stay at pnpm --filter docs dev (port 3004).

First Time Setup

After starting the app:

1. Navigate to http://localhost:3000
2. Sign in (not sign up) with the seed user admin@example.com / Password@saaspro. Signing up with that email collides with the seeded account. Seed already creates organizations — skip "create your first org" unless you want another
3. Explore the dashboard

Common Development Commands

# Customer apps (excludes kit-docs)
pnpm dev

# Run a specific app
pnpm --filter app dev        # Main SaaS app (port 3000)
pnpm --filter docs dev       # Customer product docs (port 3004)
pnpm kit-docs:dev            # This site — kit-docs (port 3006)
pnpm --filter storybook dev  # Component library (port 6006)

# Build the customer apps (excludes kit-docs)
pnpm build
pnpm kit-docs:build          # This site only

# Run linting checks
pnpm check

# Auto-fix linting issues
pnpm fix

# Run tests
pnpm test                    # Unit tests via turbo (app, @repo/auth, @repo/database)

# Type check the web app
pnpm --filter app typecheck

# Database commands
pnpm migrate                              # Format, generate, push schema
pnpm --filter @repo/database db:seed      # Wipe (keeps RateLimit), then seed

Troubleshooting

Port already in use

• Change the port: pnpm --filter app dev -- -p 3001

Database connection issues

• Verify DATABASE_URL in apps/web/.env.local and packages/database/.env (both are required, and must match)
• Ensure Postgres is running (docker compose up -d postgres maildev)
• Check Neon credentials if using Neon

Caught email (password reset, magic link, verify)

• MailDev UI: http://localhost:1080 (SMTP localhost:1025)

Dependencies not installing

• Clear pnpm cache: pnpm store prune
• Delete node_modules and reinstall: rm -rf node_modules && pnpm install

Build fails

• Ensure all environment variables are set
• Run pnpm migrate to update database schema
• Check TypeScript errors: pnpm --filter app typecheck

Next Steps

• Read the Project Structure guide
• Learn about Features
• Understand the Database Design
• Review Deployment options