Advanced Configuration | Client Guides

This guide covers all available environment variables and advanced configuration options for your SaaS application. If you're just getting started, see the Quick Start guide for essential setup.

ℹ️

When to Use This Guide

You've completed the basic setup and want to enable optional features
You're configuring production environment variables
You need to understand what each environment variable does
You're adding payment providers, analytics, or email services

Complete Environment Variables Reference

Core Application

DATABASE_URL

Required • String

Database connection string. Format depends on your database type.

bash

1# Local development (SQLite)
2DATABASE_URL="file:./dev.db"
3 
4# Production (PostgreSQL)
5DATABASE_URL="postgresql://user:password@host:5432/database"
6 
7# Production (with connection pooling - recommended)
8DATABASE_URL="postgresql://user:password@host:5432/database?pgbouncer=true&connection_limit=1"

AUTH_SECRET

Required • Random String (32+ chars)

Used to encrypt session tokens and cookies. Must be different in production vs development.

bash

1# Generate with:
2openssl rand -base64 32
3 
4# Or use online generator:
5# https://generate-secret.vercel.app/32
6 
7AUTH_SECRET=your_very_random_secret_here

🚨

NEVER use the same secret in development and production!

AUTH_URL

Required • URL

The canonical URL of your application. Critical for OAuth redirects.

bash

1# Local development
2AUTH_URL=http://localhost:3000
3 
4# Production
5AUTH_URL=https://yourdomain.com
6 
7# Custom port
8AUTH_URL=http://localhost:3001

OAuth Providers

GitHub OAuth

Optional • OAuth Credentials

bash

1GITHUB_ID=your_github_client_id
2GITHUB_SECRET=your_github_client_secret

Get from: GitHub Developer Settings

Google OAuth

Optional • OAuth Credentials

bash

1GOOGLE_ID=your_google_client_id.apps.googleusercontent.com
2GOOGLE_SECRET=your_google_client_secret

Get from: Google Cloud Console

Payment Providers

Stripe

Optional • Payment Integration

bash

1# Publishable key (visible to frontend)
2NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
3 
4# Secret key (server-side only)
5STRIPE_SECRET_KEY=sk_test_...
6 
7# Webhook secret (for webhook signature verification)
8STRIPE_WEBHOOK_SECRET=whsec_...

Get from: Stripe Dashboard → API Keys

💡

Use test keys (pk_test_ and sk_test_) for development. Switch to live keys (pk_live_ and sk_live_) for production.

LemonSqueezy

Optional • Payment Integration (Alternative to Stripe)

bash

1LEMONSQUEEZY_API_KEY=your_api_key
2LEMONSQUEEZY_STORE_ID=your_store_id
3LEMONSQUEEZY_WEBHOOK_SECRET=your_webhook_secret

Get from: LemonSqueezy → Settings → API

Email Configuration

Email Provider Settings

Optional • Transactional Emails

bash

1# Email provider (resend, sendgrid, or smtp)
2EMAIL_PROVIDER=resend
3 
4# From address
5EMAIL_FROM=noreply@yourdomain.com
6EMAIL_FROM_NAME=Your SaaS App
7 
8# Resend
9RESEND_API_KEY=re_...
10 
11# SendGrid
12SENDGRID_API_KEY=SG....
13 
14# SMTP (generic)
15SMTP_HOST=smtp.example.com
16SMTP_PORT=587
17SMTP_USER=your_smtp_username
18SMTP_PASSWORD=your_smtp_password
19SMTP_SECURE=true

See the Email System Setup guide for detailed configuration.

Analytics & Monitoring

Google Analytics

Optional

bash

1NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXXXXX

Plausible Analytics

Optional • Privacy-friendly alternative

bash

1NEXT_PUBLIC_PLAUSIBLE_DOMAIN=yourdomain.com

Sentry Error Tracking

Optional • Production error monitoring

bash

1SENTRY_DSN=https://...@sentry.io/...
2NEXT_PUBLIC_SENTRY_DSN=https://...@sentry.io/...

Environment-Specific Configuration

Development (.env.local)

Used when running npm run dev

Use SQLite for DATABASE_URL (file:./dev.db)
Use test API keys (Stripe pk_test_, sk_test_)
AUTH_URL should be http://localhost:3000
OAuth callback URLs must point to localhost

Production (Hosting Platform)

Set these in your hosting provider's environment variables panel (Vercel, Railway, etc.)

Use PostgreSQL for DATABASE_URL (from your database provider)
Use live API keys (Stripe pk_live_, sk_live_)
AUTH_URL should be your production domain (https://yourdomain.com)
OAuth callback URLs must point to your production domain
Generate a NEW AUTH_SECRET (different from development)

Public vs Private Variables

Public Variables (NEXT_PUBLIC_*)

Exposed to the browser. Use for client-side code.

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
NEXT_PUBLIC_GA_MEASUREMENT_ID
NEXT_PUBLIC_PLAUSIBLE_DOMAIN
NEXT_PUBLIC_SENTRY_DSN

Private Variables (Server-only)

Never exposed to browser. Use for secrets.

DATABASE_URL
AUTH_SECRET
STRIPE_SECRET_KEY
API keys and passwords

🚨

Security Critical

NEVER use NEXT_PUBLIC_ prefix for secrets! This exposes them to anyone who views your site's JavaScript.

Best Practices

✅

Use different values for dev and production

Never use the same AUTH_SECRET, API keys, or database in both environments.

✅

Keep .env.local in .gitignore

Your secrets should never be committed to version control.

✅

Document required variables

Use .env.example to show which variables are needed (with placeholder values only).

❌

DON'T hard-code secrets in your code

Always use environment variables for API keys, passwords, and secrets.

❌

DON'T share .env.local files

Use a secure password manager or secrets management service to share credentials with your team.

Related Guides

Environment Variables

Essential environment variable setup guide

Production Deployment

Learn how to configure environment variables for production

Billing Setup

Configure Stripe or LemonSqueezy payment providers

Email System Setup

Configure email providers for transactional emails

Complete Environment Variables Reference

Core Application

DATABASE_URL

Required • String

Database connection string. Format depends on your database type.

bash

1# Local development (SQLite)
2DATABASE_URL="file:./dev.db"
3 
4# Production (PostgreSQL)
5DATABASE_URL="postgresql://user:password@host:5432/database"
6 
7# Production (with connection pooling - recommended)
8DATABASE_URL="postgresql://user:password@host:5432/database?pgbouncer=true&connection_limit=1"

AUTH_SECRET

Required • Random String (32+ chars)

Used to encrypt session tokens and cookies. Must be different in production vs development.

bash

1# Generate with:
2openssl rand -base64 32
3 
4# Or use online generator:
5# https://generate-secret.vercel.app/32
6 
7AUTH_SECRET=your_very_random_secret_here

🚨

NEVER use the same secret in development and production!

AUTH_URL

Required • URL

The canonical URL of your application. Critical for OAuth redirects.

bash

1# Local development
2AUTH_URL=http://localhost:3000
3 
4# Production
5AUTH_URL=https://yourdomain.com
6 
7# Custom port
8AUTH_URL=http://localhost:3001

OAuth Providers

GitHub OAuth

Optional • OAuth Credentials

bash

1GITHUB_ID=your_github_client_id
2GITHUB_SECRET=your_github_client_secret

Get from: GitHub Developer Settings

Google OAuth

Optional • OAuth Credentials

bash

1GOOGLE_ID=your_google_client_id.apps.googleusercontent.com
2GOOGLE_SECRET=your_google_client_secret

Get from: Google Cloud Console

Payment Providers

Stripe

Optional • Payment Integration

bash

1# Publishable key (visible to frontend)
2NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
3 
4# Secret key (server-side only)
5STRIPE_SECRET_KEY=sk_test_...
6 
7# Webhook secret (for webhook signature verification)
8STRIPE_WEBHOOK_SECRET=whsec_...

Get from: Stripe Dashboard → API Keys

💡

Use test keys (pk_test_ and sk_test_) for development. Switch to live keys (pk_live_ and sk_live_) for production.

LemonSqueezy

Optional • Payment Integration (Alternative to Stripe)

bash

1LEMONSQUEEZY_API_KEY=your_api_key
2LEMONSQUEEZY_STORE_ID=your_store_id
3LEMONSQUEEZY_WEBHOOK_SECRET=your_webhook_secret

Get from: LemonSqueezy → Settings → API

Email Configuration

Email Provider Settings

Optional • Transactional Emails

bash

1# Email provider (resend, sendgrid, or smtp)
2EMAIL_PROVIDER=resend
3 
4# From address
5EMAIL_FROM=noreply@yourdomain.com
6EMAIL_FROM_NAME=Your SaaS App
7 
8# Resend
9RESEND_API_KEY=re_...
10 
11# SendGrid
12SENDGRID_API_KEY=SG....
13 
14# SMTP (generic)
15SMTP_HOST=smtp.example.com
16SMTP_PORT=587
17SMTP_USER=your_smtp_username
18SMTP_PASSWORD=your_smtp_password
19SMTP_SECURE=true

See the Email System Setup guide for detailed configuration.

Analytics & Monitoring

Google Analytics

Optional

bash

1NEXT_PUBLIC_GA_MEASUREMENT_ID=G-XXXXXXXXXX

Plausible Analytics

Optional • Privacy-friendly alternative

bash

1NEXT_PUBLIC_PLAUSIBLE_DOMAIN=yourdomain.com

Sentry Error Tracking

Optional • Production error monitoring

bash

1SENTRY_DSN=https://...@sentry.io/...
2NEXT_PUBLIC_SENTRY_DSN=https://...@sentry.io/...

Environment-Specific Configuration

Development (.env.local)

Used when running npm run dev

Use SQLite for DATABASE_URL (file:./dev.db)
Use test API keys (Stripe pk_test_, sk_test_)
AUTH_URL should be http://localhost:3000
OAuth callback URLs must point to localhost

Production (Hosting Platform)

Set these in your hosting provider's environment variables panel (Vercel, Railway, etc.)

Use PostgreSQL for DATABASE_URL (from your database provider)
Use live API keys (Stripe pk_live_, sk_live_)
AUTH_URL should be your production domain (https://yourdomain.com)
OAuth callback URLs must point to your production domain
Generate a NEW AUTH_SECRET (different from development)

Public vs Private Variables

Public Variables (NEXT_PUBLIC_*)

Exposed to the browser. Use for client-side code.

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
NEXT_PUBLIC_GA_MEASUREMENT_ID
NEXT_PUBLIC_PLAUSIBLE_DOMAIN
NEXT_PUBLIC_SENTRY_DSN

Private Variables (Server-only)

Never exposed to browser. Use for secrets.

DATABASE_URL
AUTH_SECRET
STRIPE_SECRET_KEY
API keys and passwords

🚨

Security Critical

NEVER use NEXT_PUBLIC_ prefix for secrets! This exposes them to anyone who views your site's JavaScript.

Best Practices

✅

Use different values for dev and production

Never use the same AUTH_SECRET, API keys, or database in both environments.

✅

Keep .env.local in .gitignore

Your secrets should never be committed to version control.

✅

Document required variables

Use .env.example to show which variables are needed (with placeholder values only).

❌

DON'T hard-code secrets in your code

Always use environment variables for API keys, passwords, and secrets.

❌

DON'T share .env.local files

Use a secure password manager or secrets management service to share credentials with your team.