Back to Help Center
Getting Started

Complete Setup Guide

Complete Setup Guide

This guide walks you through setting up your SaaS boilerplate from scratch, step by step.

Table of Contents

  1. Prerequisites
  2. Quick Preview (No Setup)
  3. Full Setup
  4. Verify Everything Works
  5. Common Issues

Prerequisites

Before you begin, make sure you have:

| Requirement | Minimum Version | Check Command | |-------------|-----------------|---------------| | npm | 8.0 or higher | npm --version | | Git | Any recent version | git --version |

Recommended tools:

  • VS Code with the following extensions:
    • ESLint
    • Tailwind CSS IntelliSense
    • Prettier
  • A terminal (Terminal.app, iTerm2, or VS Code integrated terminal)

Quick Preview (No Setup)

Want to see the boilerplate before setting up external services? You can run it immediately:

# Clone the repository
git clone https://github.com/yourusername/saas-boilerplate.git
cd saas-boilerplate

# Install dependencies
npm install

# Start the development server
npm run dev

Open http://localhost:3000 to explore:

  • Landing page with all marketing sections
  • Pricing page
  • Blog
  • Auth pages (login/signup UI)

Note: Authentication and payments will show helpful messages prompting you to configure Supabase and Stripe when you try to use them.

Full Setup

Follow these steps in order to set up all features.

Step 1: Clone and Install

# Clone the repository
git clone https://github.com/yourusername/saas-boilerplate.git

# Navigate to the project
cd saas-boilerplate

# Install dependencies
npm install

Expected output:

added 500+ packages in 30s

Step 2: Create Environment File

# Copy the example environment file
cp .env.example .env.local

Open .env.local in your editor. You'll fill in these values as you complete each service setup.

Step 3: Set Up Supabase (Authentication & Database)

Supabase provides authentication and your PostgreSQL database.

3.1 Create a Supabase Project

  1. Go to supabase.com
  2. Click "Start your project" (sign up if needed)
  3. Click "New Project"
  4. Fill in the details:
    • Organization: Select or create one
    • Project name: e.g., "my-saas-app"
    • Database password: Generate a strong password and save it
    • Region: Choose the one closest to your users
  5. Click "Create new project"
  6. Wait 1-2 minutes for the project to be created

3.2 Get Your API Keys

  1. In your Supabase project, click Settings (gear icon) in the sidebar
  2. Click API under Configuration
  3. Copy these values to your .env.local:
NEXT_PUBLIC_SUPABASE_URL=https://abcdefghijkl.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Where to find each key: | Key | Location in Supabase Dashboard | |-----|-------------------------------| | NEXT_PUBLIC_SUPABASE_URL | Project URL (top of API page) | | NEXT_PUBLIC_SUPABASE_ANON_KEY | anon public key | | SUPABASE_SERVICE_ROLE_KEY | service_role secret key |

Security Warning: The SUPABASE_SERVICE_ROLE_KEY bypasses Row Level Security. Never expose it to the client!

3.3 Run Database Migrations

Option A: Using Supabase Dashboard (Easiest)

  1. In Supabase, click SQL Editor in the sidebar
  2. Open each file in /supabase/migrations/ in order:
    • 001_profiles.sql
    • 002_subscriptions.sql
    • 003_products.sql
    • 004_prices.sql
    • 005_rls_policies.sql
  3. Copy the contents into the SQL Editor
  4. Click Run

Option B: Using Supabase CLI

# Install Supabase CLI
npm install -g supabase

# Login to Supabase
supabase login

# Link to your project (find project ref in Project Settings > General)
supabase link --project-ref your-project-ref

# Push migrations
supabase db push

3.4 Enable Google OAuth (Optional)

If you want Google sign-in:

  1. Go to Authentication > Providers in Supabase
  2. Find Google and click to expand
  3. Toggle Enable Sign in with Google
  4. You'll need OAuth credentials from Google - see SUPABASE.md for detailed steps

Step 4: Set Up Stripe (Payments)

Stripe handles subscription billing.

4.1 Create a Stripe Account

  1. Go to stripe.com
  2. Click "Start now" and create an account
  3. You can skip business verification for now (test mode works without it)

4.2 Get Your API Keys

  1. In Stripe Dashboard, click Developers in the top nav
  2. Click API keys
  3. Copy to .env.local:
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_51...
STRIPE_SECRET_KEY=sk_test_51...

Note: These are test keys (start with pk_test_ and sk_test_). Use live keys only for production.

4.3 Create Products and Prices

  1. In Stripe Dashboard, go to Products (in the sidebar)
  2. Click + Add product

Create the Pro Plan:

  • Name: Pro
  • Description: Everything you need to grow
  • Click Add another price:
    • Price 1: $29/month (Recurring, Monthly)
    • Price 2: $279/year (Recurring, Yearly)
  • Click Save product

Create the Enterprise Plan:

  • Name: Enterprise
  • Description: For large-scale operations
  • Prices: $99/month and $950/year
  • Click Save product
  1. Copy the Price IDs to .env.local:
NEXT_PUBLIC_STRIPE_PRICE_ID_PRO_MONTHLY=price_1234567890abcdef
NEXT_PUBLIC_STRIPE_PRICE_ID_PRO_YEARLY=price_abcdef1234567890
NEXT_PUBLIC_STRIPE_PRICE_ID_ENTERPRISE_MONTHLY=price_...
NEXT_PUBLIC_STRIPE_PRICE_ID_ENTERPRISE_YEARLY=price_...

Where to find Price IDs:

  • Click on a product
  • Each price shows its ID (starts with price_)
  • Click the ID to copy it

4.4 Set Up Webhook for Local Development

Webhooks let Stripe notify your app about events (successful payments, cancellations, etc.).

  1. Install Stripe CLI:
# macOS
brew install stripe/stripe-cli/stripe

# Windows
scoop install stripe

# npm (all platforms)
npm install -g stripe
  1. Login to Stripe CLI:
stripe login
  1. Forward webhooks to your local server:
stripe listen --forward-to localhost:3000/api/stripe/webhooks
  1. Copy the webhook signing secret (shown in terminal output):
> Ready! Your webhook signing secret is whsec_1234567890abcdef...
  1. Add to .env.local:
STRIPE_WEBHOOK_SECRET=whsec_1234567890abcdef...

Keep this terminal running while testing payments locally.

Step 5: Set Up Resend (Emails)

Resend sends transactional emails (welcome, payment confirmation, etc.).

5.1 Create a Resend Account

  1. Go to resend.com
  2. Click "Start for Free"
  3. Sign up and verify your email

5.2 Get Your API Key

  1. In Resend dashboard, click API Keys
  2. Click Create API Key
  3. Name it (e.g., "Development")
  4. Copy the key to .env.local:
RESEND_API_KEY=re_123456789...

Note: The API key is only shown once. Save it securely!

5.3 Configure Email Sender (Optional for Development)

For development, emails are sent from onboarding@resend.dev. For production, add:

EMAIL_FROM="YourApp <noreply@yourapp.com>"
EMAIL_REPLY_TO=support@yourapp.com

See RESEND.md for domain verification.

Step 6: Set App URL

# Development
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Change this for production
# NEXT_PUBLIC_APP_URL=https://yourdomain.com

Step 7: Start the Development Server

npm run dev

Open http://localhost:3000

Verify Everything Works

Run through this checklist to confirm your setup is complete:

Authentication Test

  1. [ ] Go to /auth/sign-up
  2. [ ] Sign up with email and password
  3. [ ] Check your email for verification (if Resend is configured)
  4. [ ] Log in at /auth/login
  5. [ ] Verify you're redirected to /dashboard

Payment Test

  1. [ ] Make sure stripe listen is running in a terminal
  2. [ ] Go to /pricing
  3. [ ] Click "Start Free Trial" on the Pro plan
  4. [ ] Complete checkout with test card: 4242 4242 4242 4242
    • Any future expiration date (e.g., 12/34)
    • Any 3-digit CVC
    • Any billing address
  5. [ ] Verify you're redirected back to the dashboard
  6. [ ] Check that subscription status shows in /dashboard/billing

Email Test (if Resend configured)

  1. [ ] Sign up with a new email address
  2. [ ] Check that you received the welcome email

Database Test

  1. [ ] Go to Supabase Dashboard > Table Editor
  2. [ ] Check that profiles table has your user
  3. [ ] Check that subscriptions table has your subscription (after payment test)

Your Complete .env.local File

Here's what your complete environment file should look like:

# Supabase
NEXT_PUBLIC_SUPABASE_URL=https://yourproject.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Stripe
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_51...
STRIPE_SECRET_KEY=sk_test_51...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_STRIPE_PRICE_ID_FREE=price_free
NEXT_PUBLIC_STRIPE_PRICE_ID_PRO_MONTHLY=price_...
NEXT_PUBLIC_STRIPE_PRICE_ID_PRO_YEARLY=price_...
NEXT_PUBLIC_STRIPE_PRICE_ID_ENTERPRISE_MONTHLY=price_...
NEXT_PUBLIC_STRIPE_PRICE_ID_ENTERPRISE_YEARLY=price_...

# Resend
RESEND_API_KEY=re_...

# App
NEXT_PUBLIC_APP_URL=http://localhost:3000

Common Issues

"supabaseUrl is required"

Cause: Supabase environment variables not set or not loaded.

Solution:

  1. Check .env.local has NEXT_PUBLIC_SUPABASE_URL
  2. Restart the dev server (npm run dev)
  3. Make sure the file is named .env.local (not .env)

"Invalid API key" from Stripe

Cause: Stripe keys are incorrect or mixed up.

Solution:

  1. Verify you're using test keys (start with pk_test_ and sk_test_)
  2. Check for extra spaces when copying
  3. Make sure publishable key goes in NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY

Webhooks not triggering

Cause: Stripe CLI not running or wrong webhook secret.

Solution:

  1. Run stripe listen --forward-to localhost:3000/api/stripe/webhooks
  2. Copy the whsec_... secret to .env.local
  3. Restart your dev server

"Failed to fetch" or network errors

Cause: Dev server not running or wrong port.

Solution:

  1. Make sure npm run dev is running
  2. Check you're accessing http://localhost:3000 (not 3001)
  3. Check for any errors in the terminal

Google OAuth not working

Cause: OAuth not configured in Supabase or Google.

Solution: See SUPABASE.md for complete Google OAuth setup instructions.

Emails not being sent

Cause: Resend API key not set or invalid.

Solution:

  1. Check RESEND_API_KEY is set in .env.local
  2. Verify the key in Resend dashboard is active
  3. Check Resend dashboard for error logs

Next Steps

Once your setup is verified:

  1. Customize your app - Branding, colors, content
  2. Set up your pricing - Modify plans and features
  3. Customize emails - Edit email templates
  4. Add blog posts - Create content
  5. Deploy to production - Go live!

Getting Help

If you're stuck:

  1. Check the specific guide for the service you're having trouble with:

  2. Search for your error message in the troubleshooting sections

  3. Check that all environment variables are set correctly

  4. Make sure you've restarted the dev server after changing .env.local