Environment Variables | Client Guides

🚀 Just need the basics?

The Quick Start guide covers essential environment variables to get you running fast. This guide provides comprehensive details.

Environment variables are configuration values that change depending on where your app is running (local development vs production). They're used for API keys, database connections, and other sensitive data that shouldn't be committed to your code repository.

ℹ️

Prerequisites

Completed installation
Basic understanding of environment variables
Text editor to create .env.local file

ℹ️

What You'll Learn

How to create and configure your .env.local file
What each environment variable does
Required vs optional variables
Best practices for managing secrets

Understanding Environment Files

This project uses different environment files for different purposes:

📁project-root

📄.env.example

📄.env.local

📄.env.production

📄.gitignore

.env.example

Template file showing which variables are needed. Safe to commit to Git.

.env.local

Your actual secrets for local development. NEVER commit to Git!

.env.production

Optional file for production builds. Usually not needed (use hosting platform's env settings instead).

🚨

Security Critical

The .env.local file contains sensitive secrets (API keys, database passwords, etc.). It must NEVER be committed to Git. It's already in .gitignore by default - don't remove it!

Setting Up Your .env.local File

Create the File

In your project root directory, create a new file called .env.local

Using the terminal:

bash

1# macOS/Linux/Git Bash
2touch .env.local
3 
4# Windows PowerShell
5New-Item .env.local

Or create it manually in your code editor.

💡

If you have a .env.example file, you can copy it:

bash

1cp .env.example .env.local

Then fill in the actual values.

Add Required Variables

Here's a complete .env.local template with all variables this project uses:

.env.local

1# =============================================================================
2# REQUIRED FOR ALL ENVIRONMENTS
3# =============================================================================
4 
5# Database Connection
6# For local dev: SQLite (file-based, no setup needed)
7# For production: PostgreSQL URL from your hosting provider
8DATABASE_URL="file:./dev.db"
9 
10# Auth.js Configuration
11# Generate a random secret: openssl rand -base64 32
12AUTH_SECRET=your_random_secret_here
13AUTH_URL=http://localhost:3000
14 
15# App URL (used for OAuth callbacks and email links)
16NEXT_PUBLIC_APP_URL=http://localhost:3000
17 
18# =============================================================================
19# OAUTH PROVIDERS (at least one required for login to work)
20# =============================================================================
21 
22# GitHub OAuth (optional but recommended)
23# Get from: https://github.com/settings/developers
24AUTH_GITHUB_ID=
25AUTH_GITHUB_SECRET=
26 
27# Google OAuth (optional but recommended)
28# Get from: https://console.cloud.google.com/
29AUTH_GOOGLE_ID=
30AUTH_GOOGLE_SECRET=
31 
32# =============================================================================
33# PAYMENT PROVIDERS (optional - only needed if using billing)
34# =============================================================================
35 
36# Stripe (optional)
37# Get from: https://dashboard.stripe.com/apikeys
38NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=
39STRIPE_SECRET_KEY=
40STRIPE_WEBHOOK_SECRET=
41 
42# LemonSqueezy (optional alternative to Stripe)
43# Get from: https://app.lemonsqueezy.com/settings/api
44LEMONSQUEEZY_API_KEY=
45LEMONSQUEEZY_STORE_ID=
46LEMONSQUEEZY_WEBHOOK_SECRET=
47 
48# =============================================================================
49# OPTIONAL FEATURES
50# =============================================================================
51 
52# Email Provider (for transactional emails - optional)
53# Example: Resend, SendGrid, Postmark
54EMAIL_SERVER=smtp://user:pass@smtp.example.com:587
55EMAIL_FROM=noreply@yourdomain.com
56 
57# Analytics (optional)
58NEXT_PUBLIC_GA_MEASUREMENT_ID=
59NEXT_PUBLIC_PLAUSIBLE_DOMAIN=
60 
61# Sentry Error Tracking (optional)
62SENTRY_DSN=
63NEXT_PUBLIC_SENTRY_DSN=

Fill in Your Values

Replace the placeholder values with your actual credentials. Here's what you need to do for each section:

1. Database URL

For local development, keep it as file:./dev.db

For production, you'll get a PostgreSQL URL from your hosting provider (Vercel, Railway, Supabase, etc.)

2. AUTH_SECRET

Generate a random secret with this command:

bash

1openssl rand -base64 32

Copy the output and paste it as the value.

3. GitHub OAuth (Optional)

Get your credentials from GitHub Developer Settings

bash

1AUTH_GITHUB_ID=your_github_client_id
2AUTH_GITHUB_SECRET=your_github_client_secret

4. Google OAuth (Optional)

Get your credentials from Google Cloud Console

bash

1AUTH_GOOGLE_ID=your_google_client_id.apps.googleusercontent.com
2AUTH_GOOGLE_SECRET=your_google_client_secret

Variable Reference Guide

DATABASE_URL

Required • String

Connection string for your database. Format depends on database type:

SQLite (dev): file:./dev.db
PostgreSQL: postgresql://user:pass@host:5432/dbname

AUTH_SECRET

Required • Random String (32+ chars)

Used to encrypt session tokens and cookies. Must be a random string. Generate with openssl rand -base64 32

AUTH_URL

Required • URL

The base URL of your application. Local dev: http://localhost:3000 | Production: https://yourdomain.com

NEXT_PUBLIC_APP_URL

Required • URL

Public-facing app URL used for OAuth callbacks and email links. Same as AUTH_URL but exposed to client-side code.

ADMIN_EMAIL

Required • Email

Bootstrap admin email. This user always has admin access. Additional admins can be added via the admin panel.

AUTH_GITHUB_ID & AUTH_GITHUB_SECRET

Optional • OAuth Credentials

OAuth app credentials from GitHub. Required if you want GitHub login. Get from GitHub Developer Settings

AUTH_GOOGLE_ID & AUTH_GOOGLE_SECRET

Optional • OAuth Credentials

OAuth client credentials from Google Cloud Console. Required if you want Google login.

STRIPE_* Variables

Optional • Payment Integration

Only needed if using Stripe for billing. See Billing Setup guide.

LEMONSQUEEZY_* Variables

Optional • Payment Integration

Alternative to Stripe. Only needed if using LemonSqueezy for billing.

Best Practices

✅

DO: Use strong, random secrets

Generate all secrets with cryptographically secure random generators, not keyboard mashing.

✅

DO: Keep .env.local in .gitignore

Never commit your actual secrets to version control. Use .env.example for templates only.

✅

DO: Use different secrets for dev and production

Your production AUTH_SECRET should be different from your local one.

❌

DON'T: Share .env.local files

Don't send your .env.local file via email, Slack, or any other channel. Share credentials securely (1Password, etc.)

❌

DON'T: Use quotes unless necessary

Values don't need quotes in .env files. Just KEY=value, not KEY="value"

❌

DON'T: Commit real secrets to .env.example

The .env.example file should only contain placeholder values like your_secret_here

Troubleshooting

"Environment variable not found" Error

If you see this error in the console:

Check that .env.local exists in the project root (not in a subdirectory)
Verify the variable name is spelled correctly (they're case-sensitive)
Make sure there are no spaces around the = sign
Restart your dev server after adding/changing variables

Variables Not Loading

If changes to .env.local don't seem to take effect:

Stop your dev server completely (Ctrl+C)
Restart with npm run dev
Check the file is named exactly .env.local (not .env.local.txt)
Verify you're editing the file in the project root, not a subfolder

Public vs Private Variables

Variables prefixed with NEXT_PUBLIC_ are exposed to the browser. Others are server-side only.

Use NEXT_PUBLIC_ for: API endpoints, public keys, feature flags
DON'T use NEXT_PUBLIC_ for: Secrets, API keys, database URLs

Can't See .env Files in File Explorer

Files starting with a dot are hidden by default on some systems.

Solution: Use your code editor's file browser, or enable "Show hidden files" in your OS settings.

Related Guides

Installation

Get the project running on your local machine

Adding OAuth Providers

Configure OAuth providers using your environment variables

Production Deployment

Learn how to configure environment variables for production

Next Steps

Now that your environment variables are configured:

Adding OAuth Providers → Configure OAuth providers using your env variables
Setup Billing → Add payment processing (optional)
Production Deployment → Learn how to set environment variables for production

Understanding Environment Files

This project uses different environment files for different purposes:

📁project-root

📄.env.example

📄.env.local

📄.env.production

📄.gitignore

.env.example

Template file showing which variables are needed. Safe to commit to Git.

.env.local

Your actual secrets for local development. NEVER commit to Git!

.env.production

Optional file for production builds. Usually not needed (use hosting platform's env settings instead).

🚨

Security Critical

The .env.local file contains sensitive secrets (API keys, database passwords, etc.). It must NEVER be committed to Git. It's already in .gitignore by default - don't remove it!

Setting Up Your .env.local File

Create the File

In your project root directory, create a new file called .env.local

Using the terminal:

bash

1# macOS/Linux/Git Bash
2touch .env.local
3 
4# Windows PowerShell
5New-Item .env.local

Or create it manually in your code editor.

💡

If you have a .env.example file, you can copy it:

bash

1cp .env.example .env.local

Then fill in the actual values.

Add Required Variables

Here's a complete .env.local template with all variables this project uses:

.env.local

1# =============================================================================
2# REQUIRED FOR ALL ENVIRONMENTS
3# =============================================================================
4 
5# Database Connection
6# For local dev: SQLite (file-based, no setup needed)
7# For production: PostgreSQL URL from your hosting provider
8DATABASE_URL="file:./dev.db"
9 
10# Auth.js Configuration
11# Generate a random secret: openssl rand -base64 32
12AUTH_SECRET=your_random_secret_here
13AUTH_URL=http://localhost:3000
14 
15# App URL (used for OAuth callbacks and email links)
16NEXT_PUBLIC_APP_URL=http://localhost:3000
17 
18# =============================================================================
19# OAUTH PROVIDERS (at least one required for login to work)
20# =============================================================================
21 
22# GitHub OAuth (optional but recommended)
23# Get from: https://github.com/settings/developers
24AUTH_GITHUB_ID=
25AUTH_GITHUB_SECRET=
26 
27# Google OAuth (optional but recommended)
28# Get from: https://console.cloud.google.com/
29AUTH_GOOGLE_ID=
30AUTH_GOOGLE_SECRET=
31 
32# =============================================================================
33# PAYMENT PROVIDERS (optional - only needed if using billing)
34# =============================================================================
35 
36# Stripe (optional)
37# Get from: https://dashboard.stripe.com/apikeys
38NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=
39STRIPE_SECRET_KEY=
40STRIPE_WEBHOOK_SECRET=
41 
42# LemonSqueezy (optional alternative to Stripe)
43# Get from: https://app.lemonsqueezy.com/settings/api
44LEMONSQUEEZY_API_KEY=
45LEMONSQUEEZY_STORE_ID=
46LEMONSQUEEZY_WEBHOOK_SECRET=
47 
48# =============================================================================
49# OPTIONAL FEATURES
50# =============================================================================
51 
52# Email Provider (for transactional emails - optional)
53# Example: Resend, SendGrid, Postmark
54EMAIL_SERVER=smtp://user:pass@smtp.example.com:587
55EMAIL_FROM=noreply@yourdomain.com
56 
57# Analytics (optional)
58NEXT_PUBLIC_GA_MEASUREMENT_ID=
59NEXT_PUBLIC_PLAUSIBLE_DOMAIN=
60 
61# Sentry Error Tracking (optional)
62SENTRY_DSN=
63NEXT_PUBLIC_SENTRY_DSN=

Fill in Your Values

Replace the placeholder values with your actual credentials. Here's what you need to do for each section:

1. Database URL

For local development, keep it as file:./dev.db

For production, you'll get a PostgreSQL URL from your hosting provider (Vercel, Railway, Supabase, etc.)

2. AUTH_SECRET

Generate a random secret with this command:

bash

1openssl rand -base64 32

Copy the output and paste it as the value.

3. GitHub OAuth (Optional)

Get your credentials from GitHub Developer Settings

bash

1AUTH_GITHUB_ID=your_github_client_id
2AUTH_GITHUB_SECRET=your_github_client_secret

4. Google OAuth (Optional)

Get your credentials from Google Cloud Console

bash

1AUTH_GOOGLE_ID=your_google_client_id.apps.googleusercontent.com
2AUTH_GOOGLE_SECRET=your_google_client_secret

Variable Reference Guide

DATABASE_URL

Required • String

Connection string for your database. Format depends on database type:

SQLite (dev): file:./dev.db
PostgreSQL: postgresql://user:pass@host:5432/dbname

AUTH_SECRET

Required • Random String (32+ chars)

Used to encrypt session tokens and cookies. Must be a random string. Generate with openssl rand -base64 32

AUTH_URL

Required • URL

The base URL of your application. Local dev: http://localhost:3000 | Production: https://yourdomain.com

NEXT_PUBLIC_APP_URL

Required • URL

Public-facing app URL used for OAuth callbacks and email links. Same as AUTH_URL but exposed to client-side code.

ADMIN_EMAIL

Required • Email

Bootstrap admin email. This user always has admin access. Additional admins can be added via the admin panel.

AUTH_GITHUB_ID & AUTH_GITHUB_SECRET

Optional • OAuth Credentials

OAuth app credentials from GitHub. Required if you want GitHub login. Get from GitHub Developer Settings

AUTH_GOOGLE_ID & AUTH_GOOGLE_SECRET

Optional • OAuth Credentials

OAuth client credentials from Google Cloud Console. Required if you want Google login.

STRIPE_* Variables

Optional • Payment Integration

Only needed if using Stripe for billing. See Billing Setup guide.

LEMONSQUEEZY_* Variables

Optional • Payment Integration

Alternative to Stripe. Only needed if using LemonSqueezy for billing.

Best Practices

✅

DO: Use strong, random secrets

Generate all secrets with cryptographically secure random generators, not keyboard mashing.

✅

DO: Keep .env.local in .gitignore

Never commit your actual secrets to version control. Use .env.example for templates only.

✅

DO: Use different secrets for dev and production

Your production AUTH_SECRET should be different from your local one.

❌

DON'T: Share .env.local files

Don't send your .env.local file via email, Slack, or any other channel. Share credentials securely (1Password, etc.)

❌

DON'T: Use quotes unless necessary

Values don't need quotes in .env files. Just KEY=value, not KEY="value"

❌

DON'T: Commit real secrets to .env.example

The .env.example file should only contain placeholder values like your_secret_here

Troubleshooting

"Environment variable not found" Error

If you see this error in the console:

Check that .env.local exists in the project root (not in a subdirectory)
Verify the variable name is spelled correctly (they're case-sensitive)
Make sure there are no spaces around the = sign
Restart your dev server after adding/changing variables

Variables Not Loading

If changes to .env.local don't seem to take effect:

Stop your dev server completely (Ctrl+C)
Restart with npm run dev
Check the file is named exactly .env.local (not .env.local.txt)
Verify you're editing the file in the project root, not a subfolder

Public vs Private Variables

Variables prefixed with NEXT_PUBLIC_ are exposed to the browser. Others are server-side only.

Use NEXT_PUBLIC_ for: API endpoints, public keys, feature flags
DON'T use NEXT_PUBLIC_ for: Secrets, API keys, database URLs

Can't See .env Files in File Explorer

Files starting with a dot are hidden by default on some systems.

Solution: Use your code editor's file browser, or enable "Show hidden files" in your OS settings.