Environment Variables Reference

Generate Authentication Secret

openssl rand -base64 32

This generates a random 32-character secret key for encrypting sessions.

Add to .env.local:

# Core Authentication
BETTER_AUTH_SECRET=your-generated-secret-here
BETTER_AUTH_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3000

Why these are required:

• BETTER_AUTH_SECRET: Encrypts user sessions and tokens
• BETTER_AUTH_URL: Base URL for authentication callbacks
• NEXT_PUBLIC_APP_URL: Public-facing application URL (exposed to browser)

Configure Database Connection

For PostgreSQL (Recommended for production):

# Database
DATABASE_URL=postgresql://username:password@host:5432/database?sslmode=require

Getting your database URL:

1. Local PostgreSQL:

   postgresql://postgres:password@localhost:5432/nextdevkit

2. Neon (Free tier available):

   • Visit neon.tech
   • Create project → Copy connection string
   • Use the pooled connection string

3. Supabase:

   • Visit supabase.com
   • Project Settings → Database → Connection String
   • Use "Connection Pooling" string

Why you need this: Database stores user accounts, subscriptions, and application data.

See detailed database setup: Database Configuration

Run Database Migrations

# Generate migration files
pnpm db:generate

# Apply migrations to your database
pnpm db:migrate

What this does: Creates necessary tables for authentication, users, subscriptions, etc.

Choose Email Provider

NEXTDEVKIT supports Resend by default (recommended for ease of use).

Why Resend:

• Free tier: 3,000 emails/month
• No credit card required
• Simple setup
• Good deliverability

Alternatives:

• SendGrid
• AWS SES
• Postmark

Get Resend API Key

1. Visit resend.com and sign up
2. Go to API Keys → Create API Key
3. Name it (e.g., "NEXTDEVKIT Development")
4. Copy the key (starts with re_)

Create Audience for Newsletter:

1. Go to Audiences → Create Audience
2. Name it (e.g., "NEXTDEVKIT Newsletter")
3. Copy the Audience ID

Add Email Configuration

# Email Service
RESEND_API_KEY=re_your_api_key_here
RESEND_AUDIENCE_ID=your-audience-id-here

What these enable:

• Password reset emails
• Email verification
• Newsletter subscriptions
• Contact form submissions

Configure GitHub OAuth

1. Create GitHub OAuth App:

• Visit GitHub Developer Settings
• Click OAuth Apps → New OAuth App

2. Fill in details:

Application name: NEXTDEVKIT (Development)
Homepage URL: http://localhost:3000
Authorization callback URL: http://localhost:3000/api/auth/callback/github

3. Get credentials:

• Click Generate a new client secret
• Copy Client ID and Client Secret

4. Add to environment:

# GitHub OAuth
GITHUB_CLIENT_ID=Ov23xxxxxxxxxxxxx
GITHUB_CLIENT_SECRET=your-github-client-secret

Configure Google OAuth

1. Create Google Cloud Project:

• Visit Google Cloud Console
• Create new project or select existing

2. Enable Google+ API:

• Go to APIs & Services → Library
• Search "Google+ API" → Enable

3. Create OAuth Credentials:

• Go to APIs & Services → Credentials
• Click Create Credentials → OAuth client ID
• Application type: Web application

4. Configure OAuth consent screen:

• User Type: External
• Add required information (app name, support email)

5. Add authorized origins and redirect URIs:

Authorized JavaScript origins:
http://localhost:3000

Authorized redirect URIs:
http://localhost:3000/api/auth/callback/google

6. Get credentials:

# Google OAuth
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-your-client-secret

Choose Payment Provider

Stripe (Recommended):

• Industry standard
• Excellent documentation
• Supports most countries
• Advanced features (trials, metering, etc.)

Creem:

• Merchant of Record (handles tax compliance)
• Good for global sales
• Simpler tax handling

Configure Stripe

1. Create Stripe Account:

• Visit stripe.com
• Sign up and verify your account

2. Get API Keys:

• Go to Developers → API keys
• Copy Secret key (starts with sk_test_ for testing)

3. Create Products:

Create three products in Stripe Dashboard:

Product 1: Pro Monthly

• Name: "Pro Plan - Monthly"
• Billing: Recurring
• Interval: Monthly
• Price: $9.99/month
• Trial: 7 days (optional)

Product 2: Pro Yearly

• Name: "Pro Plan - Yearly"
• Billing: Recurring
• Interval: Yearly
• Price: $99/year
• Trial: 30 days (optional)

Product 3: Lifetime

• Name: "Lifetime Access"
• Billing: One-time
• Price: $399

4. Copy Price IDs:

Each product has a Price ID (starts with price_). Copy these for your .env.local:

# Stripe Configuration
STRIPE_SECRET_KEY=sk_test_your_stripe_secret_key

# Subscription Price IDs
NEXT_PUBLIC_PRICE_ID_PRO_MONTHLY=price_xxxxxxxxxxxxx
NEXT_PUBLIC_PRICE_ID_PRO_YEARLY=price_xxxxxxxxxxxxx
NEXT_PUBLIC_PRICE_ID_LIFETIME=price_xxxxxxxxxxxxx

Configure Webhooks

Webhooks notify your app when payments succeed or fail.

1. Install Stripe CLI (for local testing):

# macOS
brew install stripe/stripe-cli/stripe

# Windows
scoop bucket add stripe https://github.com/stripe/scoop-stripe-cli.git
scoop install stripe

# Linux
# Download from https://github.com/stripe/stripe-cli/releases/latest

2. Login to Stripe:

stripe login

3. Forward webhooks to local server:

stripe listen --forward-to localhost:3000/api/webhooks/stripe

This command outputs a webhook secret (starts with whsec_):

STRIPE_WEBHOOK_SECRET=whsec_your_local_webhook_secret

4. For Production:

• Go to Developers → Webhooks in Stripe Dashboard
• Click Add endpoint
• URL: https://yourdomain.com/api/webhooks/stripe
• Select events:
  • checkout.session.completed
  • customer.subscription.created
  • customer.subscription.updated
  • customer.subscription.deleted
  • invoice.payment_succeeded
  • invoice.payment_failed

Alternative: Configure Creem

If you prefer Creem as your payment provider:

1. Sign up at creem.io

2. Get API credentials:

# Creem Configuration
CREEM_API_KEY=creem_test_your_api_key
CREEM_WEBHOOK_SECRET=whsec_your_webhook_secret

# Product IDs (create products in Creem dashboard)
NEXT_PUBLIC_PRICE_ID_PRO_MONTHLY=prod_your_monthly_id
NEXT_PUBLIC_PRICE_ID_PRO_YEARLY=prod_your_yearly_id
NEXT_PUBLIC_PRICE_ID_LIFETIME=prod_your_lifetime_id

3. Update payment provider in config:

payment: {
  provider: "creem",  // Change from "stripe"
  // ... rest of config
}

Choose Storage Provider

Cloudflare R2 (Recommended for most users):

• Free tier: 10GB storage, 1M reads/month
• No egress fees
• S3-compatible API
• Fast global CDN

AWS S3:

• Industry standard
• Pay-as-you-go pricing
• Extensive features
• Global availability

Alternatives:

• DigitalOcean Spaces
• Backblaze B2
• Wasabi

Configure Cloudflare R2

1. Create R2 Bucket:

• Go to Cloudflare Dashboard → R2
• Create bucket (e.g., "nextdevkit-avatars")

2. Get API Tokens:

• Go to R2 → Manage R2 API Tokens
• Create API Token with read/write permissions
• Copy Access Key ID and Secret Access Key

3. Get Account ID:

• Found in your R2 dashboard URL or settings

4. Add to environment:

# Storage Configuration
NEXT_PUBLIC_AVATARS_BUCKET_NAME=nextdevkit-avatars

# Cloudflare R2
STORAGE_REGION=auto
STORAGE_ACCESS_KEY_ID=your-access-key-id
STORAGE_SECRET_ACCESS_KEY=your-secret-access-key
STORAGE_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com

Alternative: Configure AWS S3

1. Create S3 Bucket:

• Go to AWS Console
• Create bucket in your preferred region

2. Create IAM User:

• Go to IAM → Users → Create user
• Attach policy: AmazonS3FullAccess (or create custom policy)
• Create access key → Copy credentials

3. Add to environment:

# Storage Configuration
NEXT_PUBLIC_AVATARS_BUCKET_NAME=nextdevkit-avatars

# AWS S3
STORAGE_REGION=us-east-1
STORAGE_ACCESS_KEY_ID=AKIA...
STORAGE_SECRET_ACCESS_KEY=your-secret-key
# STORAGE_ENDPOINT not needed for AWS S3

Option 1: Google Analytics

Free, feature-rich, widely used

1. Create GA4 Property:

• Visit Google Analytics
• Create account → Create property (GA4)

2. Get Measurement ID:

• Go to Admin → Data Streams → Select your stream
• Copy Measurement ID (starts with G-)

3. Add to environment:

# Google Analytics
NEXT_PUBLIC_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX

Automatically enabled when this variable is set.

Option 2: Umami Analytics

Privacy-friendly, self-hostable, GDPR compliant

1. Choose hosting:

• Self-host: umami.is/docs
• Cloud: cloud.umami.is

2. Create website:

• Add new website in dashboard
• Copy Website ID and Script URL

3. Add to environment:

# Umami Analytics
NEXT_PUBLIC_UMAMI_WEBSITE_ID=your-website-id
NEXT_PUBLIC_UMAMI_SCRIPT_URL=https://your-umami-instance.com/script.js

Option 3: Plausible Analytics

Privacy-focused, simple, no cookies

1. Sign up:

• Visit plausible.io
• Add your domain

2. Get configuration:

# Plausible Analytics
NEXT_PUBLIC_PLAUSIBLE_DOMAIN=yourdomain.com
NEXT_PUBLIC_PLAUSIBLE_SCRIPT_URL=https://plausible.io/js/script.js

Get Google AI API Key

1. Visit Google AI Studio:

• Go to aistudio.google.com
• Sign in with Google account

2. Create API Key:

• Click Get API key
• Create in new or existing project
• Copy the key (starts with AIza)

3. Add to environment:

# AI Configuration
GOOGLE_GENERATIVE_AI_API_KEY=AIzaXXXXXXXXXXXXXXXXXXXXXXXX

Create Credit Products in Stripe

Create four credit packages in Stripe Dashboard:

1. Lite Package:

• Name: "Credits - Lite"
• Price: $9 one-time
• Credits: 100

2. Standard Package:

• Name: "Credits - Standard"
• Price: $29 one-time
• Credits: 300

3. Pro Package:

• Name: "Credits - Pro"
• Price: $79 one-time
• Credits: 1,000

4. Max Package:

• Name: "Credits - Max"
• Price: $199 one-time
• Credits: 3,000

Add Credit Price IDs

# Credits System
CREDIT_LITE_PRICE_ID=price_xxxxxxxxxxxxx
CREDIT_STANDARD_PRICE_ID=price_xxxxxxxxxxxxx
CREDIT_PRO_PRICE_ID=price_xxxxxxxxxxxxx
CREDIT_MAX_PRICE_ID=price_xxxxxxxxxxxxx

Generate Cron Secret

openssl rand -base64 16

Add to environment:

# Cron Job Security
CRON_SECRET=your-generated-secret

How it's used: Cron endpoints check this secret to prevent unauthorized access:

// Example: /api/cron/cleanup
if (request.headers.get('Authorization') !== `Bearer ${process.env.CRON_SECRET}`) {
  return new Response('Unauthorized', { status: 401 });
}

Update Authentication URLs

# Development
BETTER_AUTH_URL=http://localhost:3000

# Production
BETTER_AUTH_URL=https://yourdomain.com

Switch to Production Keys

• Stripe: sk_live_... instead of sk_test_...
• OAuth apps: Create production apps
• Database: Use production instance
• Email: Remove test mode

Update OAuth Callbacks

Register production callback URLs:

https://yourdomain.com/api/auth/callback/github
https://yourdomain.com/api/auth/callback/google

Configure Production Webhooks

• Stripe: https://yourdomain.com/api/webhooks/stripe
• Use production webhook secrets