Environment Variables

🔍 What Is It?

Next.js has two types of environment variables:

1. Server-only — available in Server Components, Route Handlers, middleware, and build scripts. Never sent to the browser.

- DATABASE_URL, API_SECRET, STRIPE_SECRET_KEY

1. Public (client-accessible) — prefixed with NEXT_PUBLIC_. Embedded in the JavaScript bundle. Visible to all users.

- NEXT_PUBLIC_API_URL, NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY

.env files (loaded in order):

• →.env — all environments
• →.env.local — local overrides (git-ignored)
• →.env.development — development only
• →.env.production — production only

🎯 Why Do We Need It?

Environment variables solve two problems:

1. Configuration per environment — different database URLs for dev, staging, and production
2. Secret management — API keys and database credentials that should never be in source code

The NEXT_PUBLIC_ prefix system ensures secrets never accidentally reach the client bundle.

🏗️ What Happens in Real Projects?

Typical .env.local for development:

DATABASE_URL="postgresql://localhost:5432/mydb"
NEXTAUTH_SECRET="dev-secret-change-in-production"
NEXTAUTH_URL="http://localhost:3000"
STRIPE_SECRET_KEY="sk_test_..."
STRIPE_WEBHOOK_SECRET="whsec_..."

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."
NEXT_PUBLIC_APP_URL="http://localhost:3000"

⚙️ How It Works

Build-time vs runtime:

• →NEXT_PUBLIC_ variables are embedded at build time. The value at build time is baked into the JS bundle. Changing the variable requires a rebuild.
• →Server-only variables are read at runtime (when the server function executes). No rebuild needed to change them.

On Vercel: Set environment variables in the Vercel dashboard. They are injected at build time (for NEXT_PUBLIC_) or at runtime (for server-only). Never commit .env.production to git.

💻 Example

Environment Variable Patterns — Type-safe env validation and correct usage in Server vs Client Components.

// lib/env.ts — Validate env vars at startup
import { z } from 'zod';

// Server-only variables
const serverSchema = z.object({
  DATABASE_URL: z.string().url(),
  NEXTAUTH_SECRET: z.string().min(32),
  STRIPE_SECRET_KEY: z.string().startsWith('sk_'),
  STRIPE_WEBHOOK_SECRET: z.string().startsWith('whsec_'),
  NODE_ENV: z.enum(['development', 'test', 'production']),
});

// Public variables
const clientSchema = z.object({
  NEXT_PUBLIC_APP_URL: z.string().url(),
  NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: z.string().startsWith('pk_'),
});

// Validate on import — fails fast if vars are missing
export const env = serverSchema.parse(process.env);
export const clientEnv = clientSchema.parse({
  NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
  NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,
});

🤔 Common Confusions

🚨 Common Production Issues

✅ Best Practices

🏛️ Architect's Note

💬 Frequently Asked Questions

🎯 Key Takeaways

🔗 Related Topics

🎯 Practice this topic in interviews

↗ Where this topic fits