Quick Start | Client Guides

🚀 Goal: Get your SaaS app running in under 15 minutes

Choose your development environment: Vercel test domain (faster path to production) or local development.

Choose Your Starting Path

Fastest to Production

☁️

Path A: Vercel Dev Environment

Best for: Faster path to production, showing stakeholders, or if you prefer cloud development.

Deploy to Vercel in 30 seconds
Use Vercel test domain (e.g., my-app.vercel.app)
Same OAuth setup as local (just different URLs)
Already deployed when ready for production

Start with Vercel Dev →

Full Setup

💻

Path B: Local Development

Best for: Starting customization immediately, having full control, or building features from day one.

Clone and run locally
Full database with SQLite (zero config)
Working authentication (GitHub login)
Edit code and see changes instantly

Start with Local Dev →

Not sure? Both paths give you the same fully-functional app. Choose Path A for faster deployment. Choose Path B for traditional local development.

☁️

Path A: Develop on Vercel

Use a Vercel test domain as your development environment

ℹ️

Why Develop on Vercel?

Your app is already deployed - no separate production deployment step later
Share your progress with teammates via a real URL
Test on real mobile devices easily
Same features as local dev (once OAuth is configured)

Clone the Repository

First, clone the repository to your local machine:

bash

1# Clone the repository
2git clone https://github.com/SubZzzzzz/KitTy-Saas-starter-kit my-saas-app
3cd my-saas-app

Deploy to Vercel (30 seconds)

Click the button below to deploy instantly:

Deploy to Vercel

Requires a free Vercel account. You'll get a .vercel.app subdomain (e.g., my-app.vercel.app).

💡

Note your URL: After deployment, copy your Vercel URL (e.g., my-saas-abc123.vercel.app). You'll need it for OAuth setup in Step 3.

Set Up Environment Variables

In your Vercel project dashboard, go to Settings → Environment Variables and add:

Vercel Environment Variables

1# Database (use Vercel Postgres or Neon - see note below)
2DATABASE_URL="postgresql://user:pass@host:5432/dbname"
3 
4# Auth Secret (generate with: openssl rand -base64 32)
5AUTH_SECRET=your_random_secret_here
6 
7# Your Vercel URL
8AUTH_URL=https://your-vercel-app.vercel.app
9NEXT_PUBLIC_APP_URL=https://your-vercel-app.vercel.app

⚠️

Database Required: Unlike local development (which uses SQLite), Vercel requires a PostgreSQL database. Use Vercel Postgres or Neon (both have free tiers).

To add environment variables:

Go to your Vercel dashboard
Select your project
Click "Settings" tab
Click "Environment Variables" in the sidebar
Add each variable and click "Save"
Redeploy your app for changes to take effect

Set Up GitHub OAuth (5 minutes)

Enable GitHub login by creating an OAuth app. This works the same way for both Vercel and local development - just use your Vercel URL instead of localhost:

Go to GitHub Developer Settings
Click "New OAuth App"
Fill in the form:
- Application name: My SaaS App (Dev)
- Homepage URL: https://your-app.vercel.app
- Authorization callback URL: https://your-app.vercel.app/api/auth/callback/github
Click "Register application"
Copy the Client ID
Click "Generate a new client secret" and copy it

Add to your Vercel environment variables:

Vercel Environment Variables

1# GitHub OAuth
2AUTH_GITHUB_ID=your_github_client_id_here
3AUTH_GITHUB_SECRET=your_github_client_secret_here

🚨

Copy the client secret immediately! GitHub only shows it once.

💡

Want to develop locally too? You can add both URLs to your GitHub OAuth app! Click "Update application" and add a second callback URL: http://localhost:3000/api/auth/callback/github

Test Login

After redeploying with your OAuth credentials, verify everything works:

Visit your Vercel URL
Click "Sign In" in the top right
Click "Sign in with GitHub"
Authorize the app when prompted
You should be redirected to the dashboard

✅ Success!

If you can see the dashboard, your app is fully functional on Vercel! You're already deployed and ready to customize.

Customize (Optional)(Optional)

Since you already have the repository cloned, install dependencies and start customizing:

bash

1# Install dependencies
2npm install
3 
4# Start the dev server to preview changes locally
5npm run dev
6 
7# Make your changes, commit, and push to redeploy automatically

ℹ️

Auto-deployment: Every time you push to your main branch, Vercel will automatically redeploy your app with the latest changes!

💻

Path B: Local Development

Full setup with working authentication

ℹ️

What You'll Need

Node.js 18+ installed (download here)
Git installed (download here)
A GitHub or Google account (for OAuth setup)
15 minutes of focused time

Local Development Steps

Clone and Install (2 minutes)

Open your terminal and run these commands:

bash

1# Clone the repository
2git clone https://github.com/SubZzzzzz/KitTy-Saas-starter-kit my-saas-app
3cd my-saas-app
4 
5# Install dependencies
6npm install
7 
8# Set up the database
9npm run db:dev

💡

Stuck? Verify Node.js is installed: node --version should show v18 or higher.

Create Environment File (1 minute)

Create a file named .env.local in the project root:

bash

1# Create the file (macOS/Linux/Git Bash)
2touch .env.local
3 
4# Or (Windows PowerShell)
5New-Item .env.local

Add these essential variables to .env.local:

.env.local

1# Database (SQLite for local dev)
2DATABASE_URL="file:./dev.db"
3 
4# Auth Secret (generate with: openssl rand -base64 32)
5AUTH_SECRET=your_random_secret_here
6AUTH_URL=http://localhost:3000
7NEXT_PUBLIC_APP_URL=http://localhost:3000
8 
9# We'll add OAuth credentials in the next step

⚠️

Generate a real secret! Run openssl rand -base64 32 and paste the output as AUTH_SECRET. No openssl? Use this generator.

Set Up GitHub OAuth (5 minutes)

Enable GitHub login by creating an OAuth app. This setup works for both local and Vercel development - just use your environment's URL:

Go to GitHub Developer Settings
Click "New OAuth App"
Fill in the form:
- Application name: My SaaS App (Dev)
- Homepage URL: http://localhost:3000 (or your Vercel URL)
- Authorization callback URL: http://localhost:3000/api/auth/callback/github (or your Vercel URL)
Click "Register application"
Copy the Client ID
Click "Generate a new client secret" and copy it

Add to your .env.local file:

.env.local

1# GitHub OAuth
2AUTH_GITHUB_ID=your_github_client_id_here
3AUTH_GITHUB_SECRET=your_github_client_secret_here

🚨

Copy the client secret immediately! GitHub only shows it once.

💡

Same setup for Vercel: If you later deploy to Vercel, use the same OAuth credentials. Just add your Vercel URL as an additional callback URL in your GitHub OAuth app settings, or update the existing URLs.

Start the App (1 minute)(Optional)

Start the development server:

bash

1npm run dev

Open your browser to:

http://localhost:3000

You should see the landing page! 🎉

Test Login (2 minutes)

Verify everything works:

Click "Sign In" in the top right
Click "Sign in with GitHub"
Authorize the app when prompted
You should be redirected to the dashboard

✅ Success!

If you can see the dashboard, your app is fully functional. You're ready to customize!

💡

Want Google login too? See Adding OAuth Providers for Google OAuth setup (adds 5-10 minutes).

Common Issues & Quick Fixes

❌ "npm: command not found"

Fix: Node.js isn't installed. Download from nodejs.org, then restart your terminal.

❌ "Redirect URI Mismatch" (GitHub)

Fix: Callback URL must be exactly http://localhost:3000/api/auth/callback/github (http not https, no trailing slash).

❌ "Configuration Error" when signing in

Fix: Check that AUTH_GITHUB_ID and AUTH_GITHUB_SECRET are in .env.local. Restart dev server with npm run dev.

❌ Port 3000 already in use

Fix: Use a different port: PORT=3001 npm run dev and update AUTH_URL to http://localhost:3001

❌ Variables not loading after editing .env.local

Fix: Stop the dev server (Ctrl+C) and restart with npm run dev. Env changes only load on server start.

Need more help?

See the Troubleshooting guide for comprehensive solutions to common problems.

Complete .env.local Example

Here's what your minimal working .env.local should look like:

.env.local

1# Database
2DATABASE_URL="file:./dev.db"
3 
4# Auth Configuration
5AUTH_SECRET=abc123def456ghi789example_replace_this
6AUTH_URL=http://localhost:3000
7NEXT_PUBLIC_APP_URL=http://localhost:3000
8 
9# GitHub OAuth
10AUTH_GITHUB_ID=Iv1.abc123example
11AUTH_GITHUB_SECRET=abc123def456ghi789example

🚨

Never commit .env.local to Git! It's already in .gitignore by default.

What You Have Now

✅ Working App

Landing page with pricing
User authentication (GitHub)
User dashboard
SQLite database
Dark mode toggle

🎨 Ready to Customize

Change colors and branding
Add your own features
Configure billing (optional)
Deploy to production

Next Steps

🎨 Customize Theme Colors →

Make it yours by changing the color palette to match your brand

✨ Add Your Logo & Branding →

Replace the default logo and update branding throughout the app

💳 Setup Billing (Optional) →

Configure Stripe or LemonSqueezy to accept payments

🚀 Deploy to Production →

Learn how to deploy your customized app to the web

Want More Detailed Explanations?

This quick start gets you running fast. For deeper understanding, check out the individual guides:

Installation Guide → Detailed explanation of the installation process
Environment Variables → Complete reference for all configuration options
Adding OAuth Providers → Add Google OAuth and learn how authentication works
Advanced Configuration → Optional environment variables and advanced settings

Choose Your Starting Path

Fastest to Production

☁️

Path A: Vercel Dev Environment

Best for: Faster path to production, showing stakeholders, or if you prefer cloud development.

Deploy to Vercel in 30 seconds
Use Vercel test domain (e.g., my-app.vercel.app)
Same OAuth setup as local (just different URLs)
Already deployed when ready for production

Start with Vercel Dev →

Full Setup

💻

Path B: Local Development

Best for: Starting customization immediately, having full control, or building features from day one.

Clone and run locally
Full database with SQLite (zero config)
Working authentication (GitHub login)
Edit code and see changes instantly

Start with Local Dev →

Not sure? Both paths give you the same fully-functional app. Choose Path A for faster deployment. Choose Path B for traditional local development.

1# Database (use Vercel Postgres or Neon - see note below) 2DATABASE_URL="postgresql://user:pass@host:5432/dbname" 3 4# Auth Secret (generate with: openssl rand -base64 32) 5AUTH_SECRET=your_random_secret_here 6 7# Your Vercel URL 8AUTH_URL=https://your-vercel-app.vercel.app 9NEXT_PUBLIC_APP_URL=https://your-vercel-app.vercel.app

1# Database (SQLite for local dev) 2DATABASE_URL="file:./dev.db" 3 4# Auth Secret (generate with: openssl rand -base64 32) 5AUTH_SECRET=your_random_secret_here 6AUTH_URL=http://localhost:3000 7NEXT_PUBLIC_APP_URL=http://localhost:3000 8 9# We'll add OAuth credentials in the next step

Common Issues & Quick Fixes

❌ "npm: command not found"

Fix: Node.js isn't installed. Download from nodejs.org, then restart your terminal.

❌ "Redirect URI Mismatch" (GitHub)

Fix: Callback URL must be exactly http://localhost:3000/api/auth/callback/github (http not https, no trailing slash).

❌ "Configuration Error" when signing in

Fix: Check that AUTH_GITHUB_ID and AUTH_GITHUB_SECRET are in .env.local. Restart dev server with npm run dev.

❌ Port 3000 already in use

Fix: Use a different port: PORT=3001 npm run dev and update AUTH_URL to http://localhost:3001

❌ Variables not loading after editing .env.local

Fix: Stop the dev server (Ctrl+C) and restart with npm run dev. Env changes only load on server start.

Need more help?

See the Troubleshooting guide for comprehensive solutions to common problems.

Complete .env.local Example

Here's what your minimal working .env.local should look like:

.env.local

1# Database
2DATABASE_URL="file:./dev.db"
3 
4# Auth Configuration
5AUTH_SECRET=abc123def456ghi789example_replace_this
6AUTH_URL=http://localhost:3000
7NEXT_PUBLIC_APP_URL=http://localhost:3000
8 
9# GitHub OAuth
10AUTH_GITHUB_ID=Iv1.abc123example
11AUTH_GITHUB_SECRET=abc123def456ghi789example

🚨

Never commit .env.local to Git! It's already in .gitignore by default.

Want More Detailed Explanations?

This quick start gets you running fast. For deeper understanding, check out the individual guides:

Installation Guide → Detailed explanation of the installation process

Environment Variables → Complete reference for all configuration options

Adding OAuth Providers → Add Google OAuth and learn how authentication works

Advanced Configuration → Optional environment variables and advanced settings

Quick Start ⚡

Choose Your Starting Path

Path A: Vercel Dev Environment

Path B: Local Development

Path A: Develop on Vercel

Why Develop on Vercel?

Clone the Repository

Deploy to Vercel (30 seconds)

Set Up Environment Variables

Set Up GitHub OAuth (5 minutes)

Test Login

Customize (Optional)(Optional)

Path B: Local Development

What You'll Need

Local Development Steps

Clone and Install (2 minutes)

Create Environment File (1 minute)

Set Up GitHub OAuth (5 minutes)

Start the App (1 minute)(Optional)

Test Login (2 minutes)

Common Issues & Quick Fixes

❌ "npm: command not found"

❌ "Redirect URI Mismatch" (GitHub)

❌ "Configuration Error" when signing in

❌ Port 3000 already in use

❌ Variables not loading after editing .env.local

Complete .env.local Example

What You Have Now

✅ Working App

🎨 Ready to Customize

Next Steps

🎨 Customize Theme Colors →

✨ Add Your Logo & Branding →

💳 Setup Billing (Optional) →

🚀 Deploy to Production →

Want More Detailed Explanations?

Quick Start ⚡

Choose Your Starting Path

Path A: Vercel Dev Environment

Path B: Local Development

Path A: Develop on Vercel

Why Develop on Vercel?

Clone the Repository

Deploy to Vercel (30 seconds)

Set Up Environment Variables

Set Up GitHub OAuth (5 minutes)

Test Login

Customize (Optional)(Optional)

Path B: Local Development

What You'll Need

Local Development Steps

Clone and Install (2 minutes)

Create Environment File (1 minute)

Set Up GitHub OAuth (5 minutes)

Start the App (1 minute)(Optional)

Test Login (2 minutes)

Common Issues & Quick Fixes

❌ "npm: command not found"

❌ "Redirect URI Mismatch" (GitHub)

❌ "Configuration Error" when signing in

❌ Port 3000 already in use

❌ Variables not loading after editing .env.local

Complete .env.local Example

What You Have Now

✅ Working App

🎨 Ready to Customize

Next Steps

🎨 Customize Theme Colors →

✨ Add Your Logo & Branding →

💳 Setup Billing (Optional) →

🚀 Deploy to Production →

Want More Detailed Explanations?