Skip to main content

​
Prerequisites

Before you begin, make sure you have the following installed:

​
Installation

1

Clone the repository

Clone the Next.js SaaS Starter to your local machine:
git clone https://github.com/nextjs/saas-starter
cd saas-starter
2

Install dependencies

Install the project dependencies using pnpm:
pnpm install
The project uses pnpm for package management. If you prefer npm or yarn, you can use those instead, but pnpm is recommended for faster installs.
3

Set up environment variables

Run the database setup script to create your .env file:
pnpm db:setup
This interactive script will prompt you for:
  • PostgreSQL connection URL
  • Stripe secret key
  • Stripe webhook secret
  • Base URL (defaults to http://localhost:3000)
  • Auth secret (auto-generated)
If you prefer to set up your .env file manually, create a .env file in the root directory:
POSTGRES_URL=postgresql://user:password@localhost:5432/saas_starter
STRIPE_SECRET_KEY=sk_test_***
STRIPE_WEBHOOK_SECRET=whsec_***
BASE_URL=http://localhost:3000
AUTH_SECRET=your-secret-here
Generate a secure AUTH_SECRET with:
openssl rand -base64 32
4

Set up the database

Run the database migrations to create the necessary tables:
pnpm db:migrate
Then seed the database with sample data:
pnpm db:seed
This creates:
  • A test user with email [email protected] and password admin123
  • A test team named “Test Team”
  • Sample Stripe products for testing
Make sure your PostgreSQL database is running before running migrations. If you’re using Docker, you can start a local PostgreSQL instance with the provided configuration.
5

Configure Stripe

Log in to the Stripe CLI:
stripe login
In a separate terminal, start listening for webhooks:
stripe listen --forward-to localhost:3000/api/stripe/webhook
Copy the webhook signing secret (starts with whsec_) and add it to your .env file:
STRIPE_WEBHOOK_SECRET=whsec_***
Keep the Stripe CLI running in a separate terminal window while developing. This allows you to test subscription events locally.
6

Start the development server

Start the Next.js development server:
pnpm dev
Open http://localhost:3000 in your browser to see your application running.

​
Testing the Application

​
Sign In with Test Account

  1. Navigate to http://localhost:3000/sign-in
  2. Use the seeded test credentials:
  3. You’ll be redirected to the dashboard

​
Create a New Account

  1. Navigate to http://localhost:3000/sign-up
  2. Fill in the registration form
  3. You’ll be automatically signed in and redirected to the dashboard

​
Test Stripe Payments

To test the subscription flow:
  1. Go to the pricing page: http://localhost:3000/pricing
  2. Click “Subscribe” on any plan
  3. Use Stripe’s test card numbers:
Card Number: 4242 4242 4242 4242
Expiration: Any future date
CVC: Any 3 digits
ZIP: Any 5 digits
All subscriptions include a 14-day free trial by default. You can modify this in lib/payments/stripe.ts:42.

​
Available Scripts

The project includes several useful npm scripts:
​
pnpm dev
command
Start the Next.js development server with Turbopack
​
pnpm build
command
Build the application for production
​
pnpm start
command
Start the production server
​
pnpm db:setup
command
Interactive setup script to create your .env file
​
pnpm db:generate
command
Generate Drizzle ORM migrations from schema changes
​
pnpm db:migrate
command
Run database migrations
​
pnpm db:seed
command
Seed the database with sample data
​
pnpm db:studio
command
Open Drizzle Studio to explore your database

​
Project Structure

saas-starter/
├── app/                    # Next.js app directory
│   ├── (dashboard)/       # Dashboard routes (protected)
│   ├── (login)/           # Authentication routes
│   └── api/               # API routes
├── components/            # UI components
│   └── ui/               # shadcn/ui components
├── lib/                   # Utility functions
│   ├── auth/             # Authentication utilities
│   ├── db/               # Database schema and queries
│   └── payments/         # Stripe integration
└── middleware.ts          # Global middleware

​
Next Steps

Now that you have the application running, explore the core features:

Authentication

Learn how JWT-based authentication works

Team Management

Understand multi-tenancy and RBAC

Stripe Integration

Explore subscription and billing features

Database Schema

View the complete database schema

​
Troubleshooting

Make sure your PostgreSQL database is running and the POSTGRES_URL in your .env file is correct.If using Docker, start PostgreSQL with:
docker run -d \
  --name saas-postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=saas_starter \
  -p 5432:5432 \
  postgres:15
Make sure the Stripe CLI is running:
stripe listen --forward-to localhost:3000/api/stripe/webhook
Verify that the STRIPE_WEBHOOK_SECRET in your .env file matches the webhook signing secret from the Stripe CLI output.
Make sure you’ve run the database seed command:
pnpm db:seed
If the problem persists, check that your AUTH_SECRET is set in the .env file.
Try clearing the Next.js cache and reinstalling dependencies:
rm -rf .next node_modules
pnpm install
pnpm dev

​
Getting Help

If you encounter issues:

Deploy to Production

Ready to deploy? Learn how to take your app to production

Build docs developers (and LLMs) love

Get started for freeTalk to us