Next.js Environment Variables Guide (2026)

If you searched nextjs environment variables or next js environment variables, you probably hit the same wall: values work in next dev, disappear in the client, or stay frozen after you change production config. The official docs are clear once you know the split between build-time inlining (NEXT_PUBLIC_) and server-only process.env, but most threads mix Docker, Vercel, and "why is my key undefined in the browser?"

This guide is a production-oriented walkthrough for App Router teams: .env load order, what to commit, NEXT_PUBLIC_ behavior, where server code can read secrets, runtime env vars with Docker and standalone output, Vercel and Cloudflare, monorepo env with Turborepo, typed validation (without repeating our Envin deep dive), and what to do if an API key leaked in .env. For auth and CSP around secrets, pair this with the Next.js security checklist.

Quotable definition: A Next.js environment variable is a key/value pair loaded from .env* files or the host OS into process.env. Only keys prefixed with NEXT_PUBLIC_ are exposed to browser bundles, and those values are fixed when you run next build.

Which .env files exist and what to commit

Next.js (and tools like @next/env) load variables from the project root, not from /src alone. In a monorepo web app, that usually means the app package root (for example apps/web) plus shared root .env files TurboStarter documents in environment variables.

TurboStarter keeps shared keys at the repo root and app-specific keys under apps/web, with secrets in .env.local for local work and in the host secret store for production. That layout matches how teams actually ship: one backend, multiple clients (web, mobile, extension).

Official reference: Environment Variable Load Order.

Environment variable load order in Next.js

When Next.js resolves process.env.MY_VAR, it stops at the first hit in this order (docs):

1. process.env (already set by the shell, Docker, Vercel, Cloudflare, and so on)
2. .env.$(NODE_ENV).local (not loaded when NODE_ENV is test)
3. .env.local (not loaded when NODE_ENV is test)
4. .env.$(NODE_ENV) (for example .env.development, .env.production)
5. .env

Example: with NODE_ENV=development, a variable in .env.development.local wins over the same key in .env.

Good to know from the docs:

• Allowed NODE_ENV values are development, production, and test.
• If NODE_ENV is unset, next dev sets development; other commands default to production.
• .env supports multiline values and $OTHER_VAR expansion (escape literal $ as \$).

For scripts outside Next (Drizzle CLI, Jest, Playwright), use loadEnvConfig from @next/env so test and migration tools see the same files as the app (docs).

NEXT_PUBLIC_ and build-time inlining (not runtime)

This is the behavior behind most nextjs environment variables client side confusion.

Non-NEXT_PUBLIC_ variables are available only in the Node.js / edge server runtime. They are not sent to the browser bundle.

To expose a value to client code, prefix it with NEXT_PUBLIC_. Next.js replaces every static reference like process.env.NEXT_PUBLIC_ANALYTICS_ID with the string literal present at next build time (docs).

Implications:

• Changing NEXT_PUBLIC_* in Vercel or Docker after build does not update client bundles until you rebuild.
• Promoting one Docker image from staging to production without rebuilding freezes public env in the staging values unless you planned for it.
• Dynamic lookups are not inlined, for example process.env[variableName] or const env = process.env; env.NEXT_PUBLIC_X. Do not rely on those patterns for client config.

// Inlined at build time when referenced directly
const posthogKey = process.env.NEXT_PUBLIC_POSTHOG_KEY;

// NOT inlined — do not use for client secrets or feature flags you expect to toggle without rebuild
const name = "NEXT_PUBLIC_POSTHOG_KEY";
const dynamic = process.env[name];

TurboStarter maps marketing and analytics keys under NEXT_PUBLIC_ in apps/web/env.config.ts and keeps billing, database, and auth secrets server-side. See Secrets and environment for naming rules.

Server-only access: where secrets are safe

Use server-only modules for anything that must not reach the client. Next.js recommends keeping process.env reads in server code paths (environment variables guide).

Runtime server values (App Router): For server-only variables, Next.js documents that you can read process.env during dynamic rendering after calling connection() from next/server, so the value is evaluated at request time rather than at static build time (runtime environment variables). That pattern helps Docker and standalone deployments: one image, different DATABASE_URL per environment, without rebaking the client bundle.

import { connection } from "next/server";

export default async function AdminBanner() {
  await connection();
  const region = process.env.DEPLOY_REGION ?? "unknown";
  return <p className="text-muted-foreground text-sm">Region: {region}</p>;
}

Proxy / middleware note: In Next.js 16, edge proxy runs with its own env scope. Do not treat proxy as your only auth gate (security guide). Secrets needed in proxy should be configured on the edge host (Vercel, Cloudflare) explicitly.

Docker, standalone output, and runtime env vars

nextjs docker environment variables searches usually mean: "I passed -e DATABASE_URL=... but the client still cannot see my API key." Server secrets should work at container start; client public vars need to be present during next build inside the image build stage.

TurboStarter's Docker self-host guide sets output: "standalone" so the runtime image stays small. Typical pattern:

1. Build stage: pass NEXT_PUBLIC_* as build args if they must match that image's environment.
2. Run stage: pass server secrets with docker run -e or your orchestrator's secret store.
3. Do not commit .env.production with real keys into the image layers; use .dockerignore.

# Build-time public config (example)
ARG NEXT_PUBLIC_URL
ENV NEXT_PUBLIC_URL=$NEXT_PUBLIC_URL

RUN pnpm exec turbo build --filter=web

docker run -p 3000:3000 \
  -e DATABASE_URL="postgresql://..." \
  -e BETTER_AUTH_SECRET="..." \
  your-image:tag

If NEXT_PUBLIC_ values differ per environment, you either rebuild per environment or avoid putting changeable config in NEXT_PUBLIC_ (serve a small runtime config from a Route Handler instead). There is no magic "reload .env in the browser" switch.

When env vars look undefined inside Docker but fine locally, check:

• File copied into image? .env.local is usually not in the image by design.
• Variable set on docker run, not only in compose env_file with wrong service name?
• Client vs server: browser code only sees NEXT_PUBLIC_* from the build that produced the bundle.

Vercel and Cloudflare env setup

Vercel environment variables nextjs is mostly about scoping: Production, Preview, and Development in the project dashboard, plus pulling the same names into local dev with vercel env pull. Server vars are injected at runtime; NEXT_PUBLIC_* are embedded at build time on Vercel's builders (Vercel env docs).

TurboStarter's default path is documented under Deploy to Vercel. Keep TURBO_ENV_MODE=loose in CI if you use Turbo on Vercel so undeclared env keys are not stripped before Next reads them (see repo .env comments).

Cloudflare Workers add a split between build-time and Worker runtime secrets. TurboStarter's Cloudflare deploy guide walks through Wrangler vars, .dev.vars for preview, and dashboard secrets for production. Hyperdrive and R2 bindings are separate from plain string env, but DATABASE_URL-class secrets still belong in Worker secrets, not in client bundles.

For Edge Kit on TanStack Start, see Edge Kit and Edge env docs when you outgrow Core Next.js hosting.

Typed validation: fail in CI, not in production

Manual process.env.FOO ?? "" checks do not scale across monorepos. TurboStarter validates env with Envin schemas in apps/web/env.config.ts and shared packages so next build fails when required keys are missing.

We already published a full product walkthrough: Envin type-safe environment variable validation. Use that post for CLI previews, presets, and client/server separation details. Here, the rule is simple: one schema per deployable, strict at build time, and never mark secrets as client in Envin.

Monorepo and Turborepo env handling

In a Turborepo, env vars affect cache keys. If a task reads DATABASE_URL but Turbo does not know, remote cache can serve a build from another environment's config.

TurboStarter's turbo.json declares globalEnv (for example DATABASE_URL, PRODUCT_NAME) and task-level env / passThroughEnv on build and dev. Read the full mental model in Turborepo: the ultimate guide and Advanced Turbo CLI env caching.

Practical monorepo rules:

• Put shared non-secret defaults in the root .env.
• Put Next-specific NEXT_PUBLIC_* mapping in apps/web/.env.local (see docs example).
• List any env var that changes build output in turbo.json env for that task.
• Use pnpm with-env (or your wrapper) so CLI commands load the same files as Next.

What to do if you leaked an API key in .env

Search traffic to TurboStarter docs shows real queries like exposed Lemon Squeezy, Groq, GitHub (ghp_), and Serper keys in .env files. Treat every leak as incident response, not a git revert.

After RCE-class Next.js advisories, the framework team has recommended rotating application secrets when production was unpatched (example: React2Shell guidance). The same discipline applies to leaked .env files.

Common errors and fixes

FAQ

Bottom line

Nextjs environment variables are two systems: NEXT_PUBLIC_ baked into JS at build, and server-only process.env read during requests or server startup. Respect load order, keep secrets out of Git, validate with Envin, align Turborepo cache env with turbo.json, and treat Docker plus Vercel plus Cloudflare as runtime secret injection, not a second .env in the browser.

If you want a production-ready SaaS layout (web, mobile, extension, and AI from one backend) with env schemas already wired, see TurboStarter pricing and the best SaaS starter kit 2026 comparison, then copy the environment variable docs into your first deploy checklist.