Next.js Environment Variables: .env Hierarchy, Runtime vs Build-Time, Secret Injection, and Vercel

Environment variable mistakes are one of the most common causes of Next.js production incidents: secrets accidentally exposed to the browser via NEXT_PUBLIC_, API keys baked into Docker images at build time instead of injected at runtime, and .env files committed to version control. Getting env vars right is foundational security hygiene.

This guide covers the full environment variable system in Next.js — from file precedence to runtime injection in production.

File Precedence (Lowest to Highest Priority)

.env                    # Base defaults — committed to git
.env.local              # Local overrides — NEVER commit (in .gitignore)
.env.development        # Development-only — committed to git
.env.development.local  # Local dev overrides — NEVER commit
.env.production         # Production-only — committed to git (no secrets!)
.env.production.local   # Local production overrides — NEVER commit
.env.test               # Test environment

Next.js loads files in this order; later files override earlier ones. The NODE_ENV determines which environment-specific files are loaded.

# .gitignore — always exclude local files
.env*.local
.env.production  # Exclude if it contains any real values

The NEXT_PUBLIC_ Rule

// Variables WITHOUT NEXT_PUBLIC_: server-only (never sent to browser)
DATABASE_URL=postgresql://...      // ✅ Server only
STRIPE_SECRET_KEY=sk_live_...     // ✅ Server only
OPENAI_API_KEY=sk-...             // ✅ Server only

// Variables WITH NEXT_PUBLIC_: embedded in JavaScript bundle at BUILD TIME
NEXT_PUBLIC_APP_URL=https://app.viprasol.com  // ✅ Safe — not a secret
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...  // ✅ Safe — publishable key
NEXT_PUBLIC_POSTHOG_KEY=phc_...   // ✅ Safe — client analytics key

// ❌ NEVER do this:
NEXT_PUBLIC_STRIPE_SECRET_KEY=sk_live_...  // Exposed to every browser visitor!
NEXT_PUBLIC_DATABASE_URL=postgresql://...  // Exposed to every browser visitor!

Critical: NEXT_PUBLIC_ variables are replaced with their literal values at build time by Next.js. If you change them after building, you must rebuild. They cannot be changed at runtime without a new deployment.

TypeScript: Validate Env at Startup

// lib/env.ts — validate all required env vars at module load time
// This crashes the process immediately if config is wrong,
// rather than failing silently later

import { z } from "zod";

const ServerEnvSchema = z.object({
  // Database
  DATABASE_URL:           z.string().url(),

  // Auth
  NEXTAUTH_URL:           z.string().url(),
  NEXTAUTH_SECRET:        z.string().min(32),

  // Stripe
  STRIPE_SECRET_KEY:      z.string().startsWith("sk_"),
  STRIPE_WEBHOOK_SECRET:  z.string().startsWith("whsec_"),

  // AWS
  AWS_REGION:             z.string().default("us-east-1"),
  AWS_ACCESS_KEY_ID:      z.string().optional(),
  AWS_SECRET_ACCESS_KEY:  z.string().optional(),
  S3_BUCKET_NAME:         z.string(),

  // Email
  RESEND_API_KEY:         z.string().startsWith("re_"),

  // App
  NODE_ENV:               z.enum(["development", "production", "test"]),
});

const ClientEnvSchema = z.object({
  NEXT_PUBLIC_APP_URL:                    z.string().url(),
  NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY:     z.string().startsWith("pk_"),
  NEXT_PUBLIC_POSTHOG_KEY:               z.string().optional(),
  NEXT_PUBLIC_POSTHOG_HOST:              z.string().url().optional(),
});

// Validate server env (runs only on server — process.env available)
function validateServerEnv() {
  const result = ServerEnvSchema.safeParse(process.env);
  if (!result.success) {
    console.error("❌ Invalid server environment variables:");
    console.error(result.error.flatten().fieldErrors);
    throw new Error("Invalid environment configuration — check your .env file");
  }
  return result.data;
}

// Validate client env (safe to call anywhere)
function validateClientEnv() {
  const result = ClientEnvSchema.safeParse({
    NEXT_PUBLIC_APP_URL:                process.env.NEXT_PUBLIC_APP_URL,
    NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,
    NEXT_PUBLIC_POSTHOG_KEY:           process.env.NEXT_PUBLIC_POSTHOG_KEY,
    NEXT_PUBLIC_POSTHOG_HOST:          process.env.NEXT_PUBLIC_POSTHOG_HOST,
  });
  if (!result.success) {
    throw new Error(`Invalid client env: ${JSON.stringify(result.error.flatten().fieldErrors)}`);
  }
  return result.data;
}

// Export validated, typed env objects
export const serverEnv = typeof window === "undefined"
  ? validateServerEnv()
  : ({} as ReturnType<typeof validateServerEnv>);

export const clientEnv = validateClientEnv();

// Usage:
// import { serverEnv } from "@/lib/env";
// const stripe = new Stripe(serverEnv.STRIPE_SECRET_KEY);

.env Files Structure

# .env — safe defaults, committed to git
NODE_ENV=development
NEXT_PUBLIC_APP_URL=http://localhost:3000

# .env.local — your personal secrets, NEVER commit
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/myapp_dev
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=dev-secret-at-least-32-characters-long
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
AWS_REGION=us-east-1
S3_BUCKET_NAME=myapp-dev-uploads
RESEND_API_KEY=re_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...

# .env.production — production non-secrets only, committed to git
NODE_ENV=production
NEXT_PUBLIC_APP_URL=https://app.viprasol.com
NEXT_PUBLIC_POSTHOG_HOST=https://app.posthog.com

Runtime Variables in Docker/ECS

For containerized deployments, never bake secrets into the Docker image. Inject them at runtime:

# Dockerfile — no ENV instructions for secrets
FROM node:22-alpine AS base

# Build stage: only needs NEXT_PUBLIC_ vars (baked at build time)
FROM base AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .

# Build-time NEXT_PUBLIC_ vars are passed as build args
ARG NEXT_PUBLIC_APP_URL
ARG NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
ENV NEXT_PUBLIC_APP_URL=$NEXT_PUBLIC_APP_URL
ENV NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=$NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY

RUN npm run build

# Runtime stage: server env vars injected at container start, NOT baked in
FROM base AS runner
WORKDIR /app
ENV NODE_ENV=production

COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public

EXPOSE 3000
CMD ["node", "server.js"]
# DATABASE_URL, STRIPE_SECRET_KEY, etc. come from ECS task environment
# They are NOT in the image — they're injected at task start

# terraform/ecs-task.tf — inject secrets at runtime
resource "aws_ecs_task_definition" "app" {
  family = var.app_name

  container_definitions = jsonencode([{
    name  = "app"
    image = "${var.ecr_repo}:${var.image_tag}"

    environment = [
      { name = "NODE_ENV",             value = "production" },
      { name = "AWS_REGION",           value = var.aws_region },
      # NEXT_PUBLIC_ vars are already baked into the image — no need to pass again
    ]

    secrets = [
      # Fetched from Secrets Manager at container start (not baked into image)
      { name = "DATABASE_URL",          valueFrom = "${var.secrets_arn}:DATABASE_URL::" },
      { name = "NEXTAUTH_SECRET",       valueFrom = "${var.secrets_arn}:NEXTAUTH_SECRET::" },
      { name = "STRIPE_SECRET_KEY",     valueFrom = "${var.secrets_arn}:STRIPE_SECRET_KEY::" },
      { name = "STRIPE_WEBHOOK_SECRET", valueFrom = "${var.secrets_arn}:STRIPE_WEBHOOK_SECRET::" },
      { name = "RESEND_API_KEY",        valueFrom = "${var.secrets_arn}:RESEND_API_KEY::" },
    ]
  }])
}

Vercel Environment Management

# Vercel CLI: set environment variables per environment
vercel env add DATABASE_URL production         # Production only
vercel env add DATABASE_URL preview            # Preview deployments
vercel env add DATABASE_URL development        # Local dev via vercel dev

# Pull env vars for local development (safe alternative to .env.local)
vercel env pull .env.local

# List all env vars (values are masked)
vercel env ls

# Remove a variable
vercel env rm OLD_API_KEY production

For Vercel's Edge Runtime (middleware, edge functions), only NEXT_PUBLIC_ vars and variables explicitly marked for Edge are available. Server-only vars are NOT available in Edge:

// middleware.ts — Edge Runtime
export const runtime = "edge";

// ✅ Available in Edge
const appUrl = process.env.NEXT_PUBLIC_APP_URL;

// ❌ NOT available in Edge (only in Node.js runtime)
// const db = process.env.DATABASE_URL; // undefined at edge

Server Actions and env

// app/actions/send-email.ts — Server Action
"use server";

// process.env is available in Server Actions (Node.js runtime)
import { serverEnv } from "@/lib/env";

export async function sendWelcomeEmail(userId: string) {
  // serverEnv.RESEND_API_KEY is safely available here
  const resend = new Resend(serverEnv.RESEND_API_KEY);
  // ...
}

Common Mistakes

// ❌ MISTAKE 1: Reading server env in a Client Component
"use client";
function PaymentForm() {
  // process.env.STRIPE_SECRET_KEY is undefined in browser
  // And if it were NEXT_PUBLIC_, it would be exposed!
  const key = process.env.STRIPE_SECRET_KEY; // undefined
}

// ✅ FIX: Call a Server Action or API route that uses the key server-side

// ❌ MISTAKE 2: Dynamic NEXT_PUBLIC_ variable names
const key = `NEXT_PUBLIC_${name}`; // Won't work — Next.js replaces statically at build time
process.env[key]; // undefined

// ✅ FIX: Reference NEXT_PUBLIC_ vars by their full literal name

// ❌ MISTAKE 3: Checking NODE_ENV at runtime in Edge
// Edge runtime may not have NODE_ENV set as expected
if (process.env.NODE_ENV === "production") { /* ... */ }
// Use NEXT_PUBLIC_APP_ENV or check the hostname instead at Edge

// ❌ MISTAKE 4: .env.production with real secrets committed to git
# .env.production
STRIPE_SECRET_KEY=sk_live_abc123  # ❌ Git history = permanent exposure

// ✅ FIX: Use Vercel env vars, AWS Secrets Manager, or inject via CI/CD secrets

Cost and Timeline

Environment variable setup is a one-time configuration task:

See Also

• AWS Secrets Manager and Parameter Store
• Next.js App Router Caching Strategies
• AWS ECS Fargate Production Setup
• Next.js Middleware Auth Patterns
• Docker Multi-Stage Builds

---

Working With Viprasol

Environment variable mistakes are silent until they're catastrophic — either a secret exposed in a browser bundle, or a missing variable causing a cryptic runtime error in production. Our team sets up typed, validated env schemas with Zod, cleanly separates build-time and runtime variables in Docker/ECS deployments, and manages secrets through AWS Secrets Manager rather than baking them into images.

What we deliver:

• Zod server + client env validation schema (crashes fast on misconfiguration)
• .env hierarchy with annotated comments and .gitignore setup
• Dockerfile with build-arg for NEXT_PUBLIC_ and runtime injection for secrets
• Terraform ECS task definition with Secrets Manager secrets array
• Vercel env management workflow for preview/production/development

Talk to our team about your environment and secrets management →

Or explore our web development services.