Environment Variables

Environment variables store configuration information outside your codebase. They're essential for managing sensitive data like API keys, database credentials, and environment-specific settings.

Naming Conventions

Client-Side Variables (Public)

Variables exposed to the browser must be prefixed with PUBLIC_ or NEXT_PUBLIC_:

# Next.js
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_APP_VERSION=1.0.0

# Other frameworks (Vite, Astro, etc.)
PUBLIC_API_URL=https://api.example.com
VITE_API_URL=https://api.example.com

Server-Side Variables (Private)

Server-only variables should use descriptive names without prefixes:

DATABASE_URL=postgresql://user:password@localhost:5432/db
API_SECRET_KEY=sk_live_1234567890
STRIPE_SECRET_KEY=sk_test_1234567890
JWT_SECRET=your-jwt-secret-key

Common Patterns

Database:

DATABASE_URL=postgresql://localhost:5432/mydb
DB_HOST=localhost
DB_PORT=5432
DB_NAME=mydb
DB_USER=username
DB_PASSWORD=password

API Keys:

OPENAI_API_KEY=sk-1234567890
STRIPE_SECRET_KEY=sk_test_1234567890
GITHUB_TOKEN=ghp_1234567890

Feature Flags:

ENABLE_ANALYTICS=true
DEBUG_MODE=false
MAINTENANCE_MODE=false

Environment Files

File Types

.env - Default environment variables
.env.local - Local overrides (ignored by git)
.env.development - Development-specific variables
.env.production - Production-specific variables
.env.test - Test-specific variables

Gitignore Configuration

Add this pattern to your .gitignore file:

# Environment variables & local files
.env*
!.env.example

This excludes all .env* files while keeping .env.example for documentation.

Creating .env.example

Always create a .env.example file to document required environment variables:

DATABASE_URL=postgresql://user:password@localhost:5432/dbname
API_SECRET_KEY=your-secret-key-here
NEXT_PUBLIC_API_URL=https://api.example.com

This helps other developers understand what environment variables are needed for the project.

Framework-Specific Implementation

Next.js with T3 Env

For Next.js projects, we recommend using T3 Env Next.js for type-safe environment variable validation. See their Next.js documentation for setup instructions.