This guide walks you through the complete setup process — from cloning the repository to seeing your app running in the browser. Estimated time: 10-15 minutes.
Prerequisites
Verify that you have the required tools installed before proceeding.
# Check Node.js version (requires v20.x)
node --version
# Check pnpm version (requires v9.x)
pnpm --version
# Check Git
git --version
If you need to install Node.js, we recommend using nvm:
nvm install 20
nvm use 20
Install pnpm globally:
npm install -g pnpm
Setup Steps
1
Clone the Repository
Clone the Kit repository to your local machine:
bash
git clone <your-repository-url> my-saas-app
cd my-saas-app
Replace
<your-repository-url> with the URL you received after purchase.2
Install Dependencies
Install all project dependencies using pnpm:
bash
pnpm install
pnpm is significantly faster than npm and uses less disk space through content-addressable storage. If you see a prompt about the pnpm version, confirm to proceed.
3
Set Up Environment Variables
Copy the example environment file to create your local configuration:
bash
cp apps/boilerplate/.env.example apps/boilerplate/.env.local
Never commit
.env.local to version control. It contains sensitive API keys and secrets. The file is already listed in .gitignore.For a minimal setup, you only need the database URL. Open
apps/boilerplate/.env.local and configure:bash
# Required: Your app URL
NEXT_PUBLIC_APP_URL=http://localhost:3000
# Required: Database (see next step for options)
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/nextjs_dev
DIRECT_URL=postgresql://postgres:postgres@localhost:5432/nextjs_dev
All other services (Clerk, Lemon Squeezy, Resend, etc.) can be configured later. Kit works without them in development mode.
4
Set Up the Database
You have two options for running PostgreSQL.
The easiest way to run a local database. Requires Docker Desktop.
# Start PostgreSQL in the background
pnpm db:up
This starts a PostgreSQL 15 container with the following defaults:
version: '3.8'
services:
postgres:
image: postgres:15-alpine
container_name: nextjs-boilerplate-db
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
POSTGRES_DB: nextjs_dev
ports:
- '5432:5432'
volumes:
- postgres_data:/var/lib/postgresql/data
healthcheck:
test: ['CMD-SHELL', 'pg_isready -U postgres']
interval: 5s
timeout: 5s
retries: 5
Your database URL is pre-configured in
apps/boilerplate/.env.example for this setup:DATABASE_URL=postgresql://postgres:postgres@localhost:5432/nextjs_dev
DIRECT_URL=postgresql://postgres:postgres@localhost:5432/nextjs_dev
Now generate the Prisma client and push the schema to your database:
bash
cd apps/boilerplate && npx prisma generate
cd apps/boilerplate && npx prisma db push
5
Start the Dev Server
Start the development server:
bash
pnpm dev:boilerplate
Open http://localhost:3000 in your browser. You should see the Kit homepage.
If you haven't set up Clerk authentication yet, use
pnpm dev:no-clerk instead. This starts the app with a mock authentication system so you can explore the dashboard immediately.Verify Your Setup
After starting the dev server, confirm that everything is working:
- Homepage loads — Visit http://localhost:3000 and see the marketing page
- Health endpoint — Visit http://localhost:3000/api/health and confirm you get a JSON response
- Dashboard access — If using
pnpm dev:no-clerk, navigate to http://localhost:3000/dashboard to see the dashboard with the mock user
Development Without Clerk
Kit includes a no-clerk mode for development without authentication credentials. This is useful when you want to explore the dashboard, test UI components, or work on features before setting up Clerk.
Start the boilerplate app in no-clerk mode:
bash
pnpm dev:no-clerk
In this mode, Kit uses a mock authentication system that provides a test user:
src/lib/auth/config.ts
export function shouldUseClerk(): boolean {
// Priority 0: Demo Mode always bypasses Clerk (even in production)
// This allows public demo deployments without real auth
if (process.env.NEXT_PUBLIC_DEMO_MODE === 'true') {
return false
}
// Priority 1: Never use test auth in production (safety first)
if (isProduction()) {
return true
}
// Priority 2: Use test auth in test environments (explicit disable)
if (isTestEnvironment()) {
return false
}
// Priority 3: In development, use Clerk if credentials are available
return hasClerkCredentials()
}
The mock user is automatically signed in and has access to all dashboard routes. When you are ready to set up real authentication, see the Authentication Overview.
Available Scripts
Here are the most important scripts you will use during development. All scripts run from the monorepo root:
| Script | Description |
|---|---|
pnpm dev:boilerplate | Start boilerplate dev server with hot reload (Turbopack) |
pnpm dev:no-clerk | Start boilerplate dev server without Clerk authentication |
pnpm build | Build all packages and apps |
pnpm build:boilerplate | Build boilerplate app only |
pnpm lint | Run ESLint across all packages |
pnpm typecheck | Run TypeScript type checking across all packages |
pnpm format | Format code with Prettier |
pnpm validate | Run typecheck + lint + format check across all packages |
pnpm test:unit | Run all unit tests with Vitest |
pnpm test:e2e:smoke | Run smoke E2E tests with Playwright |
pnpm db:up | Start PostgreSQL via Docker Compose |
pnpm db:down | Stop PostgreSQL container |
pnpm db:reset | Reset database (destroy + recreate + migrate) |
pnpm db:studio | Open Prisma Studio (visual database browser) |
pnpm deploy | Run quality checks and deploy to Vercel |
For Prisma commands that don't have root aliases, use
cd apps/boilerplate && before the command:bash
cd apps/boilerplate && npx prisma generate
cd apps/boilerplate && npx prisma migrate dev --name <name>