How to Use Environment Variables in Next.js (Without Leaking Them to the Browser)

Every Next.js developer hits this wall at some point. You add a .env.local file, reference process.env.MY_API_KEY in your code, and everything works fine on your machine. Then you deploy. Either the variable is missing in production, or worse, it shows up in your browser's network tab for anyone to see.

This guide explains how environment variables actually work in Next.js, what the NEXT_PUBLIC_ prefix does, how to validate them at build time, and how to configure things correctly for Vercel, Cloudflare Workers, Docker, and any CI/CD pipeline.

Environment variables are key-value pairs your app reads at runtime or build time. They let you store secrets outside source code, run the same codebase differently per environment, and prevent credentials from being hardcoded into files that get committed.

Next.js reads four .env files in a specific order. When the same variable exists in multiple files, .env.local always wins:

The loading order matters because later files override earlier ones. If you define API_URL=http://localhost:3000 in .env and API_URL=https://api.prod.com in .env.production, the production value is used during next build and next start, while the localhost value applies during next dev.

You can also use .env.development.local and .env.production.local for machine-specific overrides in each environment. These local variants are always git-ignored and take the highest priority within their environment.

Next.js runs in two contexts, and environment variables behave differently in each. By default all variables are server-only. The NEXT_PUBLIC_ prefix explicitly opts a variable into the browser bundle.

At build time, Next.js scans your code for any reference to process.env.NEXT_PUBLIC_* and replaces it with the literal string value. This means the value is baked into the JavaScript output. There is no runtime lookup, no hidden API call. The raw value sits in your JS bundle for anyone to read.

One of the most confusing aspects of Next.js environment variables is the difference between build-time and runtime resolution. Understanding this distinction prevents a whole class of deployment bugs.

NEXT_PUBLIC_ variables are always resolved at build time. Next.js literally replaces process.env.NEXT_PUBLIC_API_URL with the string "https://api.example.com" in the compiled output. If you change the variable in your hosting dashboard and do not rebuild, the old value persists in the bundle.

Server-only variables (without the NEXT_PUBLIC_ prefix) behave differently depending on your rendering strategy. In static pages generated at build time with generateStaticParams, the values are captured during next build. In API routes or server actions that run on every request, the variables are read from the runtime environment.

process.env values are always string | undefined in TypeScript. That means every access requires a null check or a type assertion, and you will not discover a missing variable until the code actually runs. For production apps, validating environment variables at build time prevents runtime crashes.

The most reliable approach is a small validation module that runs at startup. If any required variable is missing, the build fails immediately with a clear error message instead of silently producing undefined values.

With this pattern, you get autocompletion from your IDE, type safety without assertions, and an immediate build failure if someone forgets to set a variable. Every team member sees a clear error message pointing to the exact missing key.

Docker adds another layer to the equation. Variables can be injected at build time (when the image is created) or at runtime (when the container starts). Mixing these up is a frequent source of deployment bugs.

For NEXT_PUBLIC_ variables, the values must be available during docker build because Next.js inlines them at compile time. Pass them as build arguments. For server-only variables, inject them at runtime using -e flags or an env file so you can change them without rebuilding the image.

Tests need their own set of environment variables. You do not want your test suite hitting a production database or a live API. Next.js does not load .env files automatically during test runs, so you need to handle this explicitly.

If you are using Jest or Vitest, create a .env.test file and load it in your test setup. Alternatively, define test values directly in your test configuration.

After years of Next.js projects, certain environment variable mistakes come up repeatedly. Here are the most common pitfalls and their fixes.

Next.js replaces process.env.VARIABLE_NAME with the actual value using a simple string substitution at build time. If you destructure process.env, the replacement cannot find the full expression and the variable resolves to undefined.

Next.js .env files follow the dotenv convention. Quotes are optional for simple values, but they matter for values containing spaces or special characters. A common mistake is adding quotes around a URL, which includes the literal quote characters in the value.

Unlike hot module replacement for code changes, .env files are only read when the dev server starts. If you add or change a variable and do not restart next dev, the old value (or undefined) persists. This catches developers off guard because code changes update instantly, but environment changes do not.

Run through this before every deployment. These are also the most common sources of environment variable bugs:

Environment variables in Next.js are simple once the mental model clicks: server-side by default, client-side only when you opt in with NEXT_PUBLIC_, and never committed to Git when they contain secrets.

Keep a .env.example file up to date as your project grows. Add a validation module that fails the build on missing variables. Set production values in the platform dashboard, not in committed files. Pass NEXT_PUBLIC_ values as Docker build arguments and server secrets as runtime environment variables.

Run through the security checklist before every deployment. A few minutes of verification prevents the kind of credential leak that takes days to remediate.