Next.js Environment Variable Structure

Complete guide to Next.js environment variable management.

File Structure

my-nextjs-app/
├── .env                      # Shared defaults (committed)
├── .env.local               # Local secrets (gitignored)
├── .env.development         # Development defaults (committed)
├── .env.development.local   # Local dev overrides (gitignored)
├── .env.production          # Production defaults (committed)
├── .env.production.local    # Production secrets (gitignored)
├── .env.test                # Test environment (committed)
└── .env.example             # Documentation (committed)

File Precedence

Next.js loads files in this order (higher = higher precedence):

.env.$(NODE_ENV).local

(e.g.,

.env.production.local

)

```
.env.local
```
(not loaded in test environment)
```
.env.$(NODE_ENV)
```
(e.g.,
```
.env.production
```
)
```
.env
```

Example: In production, if

DATABASE_URL

is defined in both

.env

and

.env.production.local

, the value from

.env.production.local

wins.

Variable Types

Client-Side Variables (NEXT_PUBLIC_*)

Exposed to the browser. Must prefix with

NEXT_PUBLIC_

bash

# .env.local
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_ANALYTICS_ID=UA-123456789
NEXT_PUBLIC_SITE_NAME=My Awesome Site
NEXT_PUBLIC_ENABLE_FEATURE_X=true

Access in code:

javascript

// Works in both client and server
const apiUrl = process.env.NEXT_PUBLIC_API_URL;

// Usage in components
export default function MyComponent() {
  return <div>API: {process.env.NEXT_PUBLIC_API_URL}</div>;
}

⚠️ Security Warning: NEVER put secrets in

NEXT_PUBLIC_*

variables!

bash

# ❌ WRONG - Secret exposed to browser
NEXT_PUBLIC_API_SECRET=sk_live_abc123

# ✅ CORRECT - Secret only on server
API_SECRET=sk_live_abc123

Server-Side Variables

Only available in server-side code (API routes, getServerSideProps, etc.).

bash

# .env.local
DATABASE_URL=postgres://localhost:5432/mydb
JWT_SECRET=super-secret-jwt-key-do-not-expose
STRIPE_SECRET_KEY=sk_live_abc123
SMTP_PASSWORD=email-password-here

Access in code:

javascript

// ✅ Works in API routes
export default async function handler(req, res) {
  const dbUrl = process.env.DATABASE_URL;
  // Use dbUrl...
}

// ✅ Works in getServerSideProps
export async function getServerSideProps() {
  const secret = process.env.JWT_SECRET;
  // Use secret...
}

// ❌ Does NOT work in components (browser)
export default function MyComponent() {
  const dbUrl = process.env.DATABASE_URL; // undefined!
}

Example Files

.env (Committed - Shared Defaults)

bash

# Shared defaults for all environments
NEXT_PUBLIC_APP_NAME=My Next.js App
NEXT_PUBLIC_DEFAULT_LOCALE=en

# Database (overridden in .env.local)
DATABASE_URL=postgres://localhost:5432/dev

# External services (no secrets)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_abc123

.env.local (Gitignored - Local Secrets)

bash

# Local development secrets
DATABASE_URL=postgres://localhost:5432/mylocal
JWT_SECRET=dev-jwt-secret-change-in-production
STRIPE_SECRET_KEY=sk_test_local_key

# Local overrides
NEXT_PUBLIC_API_URL=http://localhost:4000/api

.env.production (Committed - Production Defaults)

bash

# Production environment defaults
NEXT_PUBLIC_API_URL=https://api.production.com
NEXT_PUBLIC_ANALYTICS_ID=UA-PROD-123456

# These will be overridden by platform env vars
DATABASE_URL=set-this-in-vercel
JWT_SECRET=set-this-in-vercel

.env.example (Committed - Documentation)

bash

# Copy this to .env.local and fill in actual values

# Client-side (browser accessible)
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_ANALYTICS_ID=your-analytics-id
NEXT_PUBLIC_SITE_NAME=Your Site Name

# Server-side (secrets)
DATABASE_URL=postgres://user:password@host:5432/database  # pragma: allowlist secret
JWT_SECRET=your-jwt-secret-32-chars-minimum
STRIPE_SECRET_KEY=sk_live_your_stripe_key
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your-email@example.com
SMTP_PASSWORD=your-smtp-password

Common Patterns

Database Configuration

bash

# Development (.env.local)
DATABASE_URL=postgres://localhost:5432/myapp_dev

# Production (Vercel Environment Variables)
DATABASE_URL=postgres://user:pass@prod-host:5432/myapp_prod  # pragma: allowlist secret

API Keys

bash

# Public keys (client-side)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_abc123

# Secret keys (server-side only)
STRIPE_SECRET_KEY=sk_live_xyz789

Feature Flags

bash

# Toggle features
NEXT_PUBLIC_ENABLE_DARK_MODE=true
NEXT_PUBLIC_ENABLE_BETA_FEATURES=false

Deployment to Vercel

Step 1: Add Environment Variables in Vercel

Go to Project Settings → Environment Variables
Add each variable:
- Key:
```
DATABASE_URL
```
- Value:
```
postgres://...
```
- Environments: Production, Preview, Development

Step 2: Separate Client vs Server Variables

Vercel automatically exposes

NEXT_PUBLIC_*

variables at build time.

bash

# Vercel automatically handles:
NEXT_PUBLIC_API_URL=https://api.example.com  # ✅ Exposed to browser

# Server-only:
DATABASE_URL=postgres://...  # ✅ Not exposed to browser

Step 3: Rebuild After Changing NEXT_PUBLIC_ Variables

⚠️ Important:

NEXT_PUBLIC_*

variables are baked into the build at build time.

If changing them in Vercel, redeploy is required:

bash

vercel --prod

Validation Workflow

1. Validate Local Environment

bash

# Check structure
python scripts/validate_env.py .env.local --framework nextjs

# Compare with .env.example
python scripts/validate_env.py .env.local --compare-with .env.example

# Check for security issues
python scripts/scan_exposed.py --check-gitignore

2. Check File Precedence

bash

# List all .env files
ls -la .env*

# Validate each
for file in .env*; do
  echo "=== $file ==="
  python scripts/validate_env.py $file --framework nextjs
done

3. Sync to Vercel

bash

# Compare local vs Vercel
python scripts/sync_secrets.py --platform vercel --compare

# Sync (dry-run first)
python scripts/sync_secrets.py --platform vercel --sync --dry-run

# Actually sync
python scripts/sync_secrets.py --platform vercel --sync --confirm

Common Issues

Issue: Variable Undefined in Browser

Symptom:

process.env.MY_VAR

undefined

in component.

Solution: Add

NEXT_PUBLIC_

prefix:

bash

# ❌ Wrong
API_URL=https://api.example.com

# ✅ Correct
NEXT_PUBLIC_API_URL=https://api.example.com

Issue: Changed Variable Not Reflected

Symptom: Changed

NEXT_PUBLIC_*

variable in Vercel, but app still uses old value.

Solution: Redeploy (variables are baked into build):

bash

vercel --prod

Issue: Works Locally, Not in Production

Symptom: App works with

.env.local

, fails in production.

Solution: Ensure all variables from

.env.local

are set in Vercel:

bash

# Compare
python scripts/sync_secrets.py --platform vercel --compare

# Find missing vars and add them in Vercel UI

Security Checklist

```
.env.local
```
in
```
.gitignore
```
```
.env.*.local
```
in
```
.gitignore
```
No secrets in
```
NEXT_PUBLIC_*
```
variables
No
```
.env
```
files committed with real secrets
```
.env.example
```
has structure, not actual values
Secrets set directly in Vercel (not in committed files)

References

Related: validation.md | security.md | frameworks.md

Related Skills

When using Nextjs, these skills enhance your workflow:

react: Core React patterns and hooks for Next.js components
tanstack-query: Server-state management with App Router and Server Components
drizzle: Type-safe ORM for Next.js server actions and API routes
prisma: Alternative ORM with excellent Next.js integration
test-driven-development: Testing Next.js App Router, Server Components, and API routes

[Full documentation available in these skills if deployed in your bundle]

nextjs-env-variables

NPX Install

Tags

SKILL.md Content

Next.js Environment Variable Structure

File Structure

File Precedence

Variable Types

Client-Side Variables (NEXT_PUBLIC_*)

Server-Side Variables

Example Files

.env (Committed - Shared Defaults)

.env.local (Gitignored - Local Secrets)

.env.production (Committed - Production Defaults)

.env.example (Committed - Documentation)

Common Patterns

Database Configuration

API Keys

Feature Flags

Deployment to Vercel

Step 1: Add Environment Variables in Vercel

Step 2: Separate Client vs Server Variables

Step 3: Rebuild After Changing NEXT_PUBLIC_ Variables

Validation Workflow

1. Validate Local Environment

2. Check File Precedence

3. Sync to Vercel

Common Issues

Issue: Variable Undefined in Browser

Issue: Changed Variable Not Reflected

Issue: Works Locally, Not in Production

Security Checklist

References

Related Skills