Managing Secrets Across Environments

Your CI job dies with TypeError: Cannot read properties of undefined (reading 'apiKey') while the same commit runs on your laptop without complaint. Nothing is wrong with the code: your laptop has a gitignored .env.local holding STRIPE_SECRET_KEY, and the CI container never saw that file. Configuration failures in Next.js are almost always precedence failures, and the order is short enough to memorize cold.

When next dev, next build, or next start boots, Next.js runs loadEnvConfig() from its internal @next/env package and reads dotenv files in a fixed order, stopping at the first place the key is found:

Three rules explain most bugs you will hit:

• A variable already present in process.env beats every file. That is why a platform's injected secret or STRIPE_KEY=sk_live_... next build outranks anything on disk — and why a forgotten shell export can silently override your .env.local and send you debugging the wrong value.
• You do not set NODE_ENV. next dev forces development; next build and next start force production. Under NODE_ENV=test, .env.local is skipped entirely so one developer's overrides cannot skew test runs; commit .env.test for the defaults everyone should share.
• $VARS inside a value are expanded from what already loaded, so TWITTER_URL=https://x.com/$TWITTER_USER style composition works, multiline quoted values survive (that is how private keys are stored), and a literal dollar is escaped as \$. There is no nested interpolation syntax beyond that.

File discipline follows directly from the table. Commit .env, .env.production, and .env.test; keep every .env*.local file out of git (the create-next-app template already ignores them); ship a .env.example listing each key with a placeholder so a new teammate knows what to fill in. If your project uses a src/ folder, the .env* files still belong at the project root — Next.js does not read them from src/.

Two consequences are worth stating plainly in an interview. First, tools outside the next CLI need the same loading behavior: a test runner or an ORM config should call loadEnvConfig(process.cwd()) from @next/env instead of hand-rolling a dotenv import, or it will disagree with the app about what DATABASE_URL is. Second, secrets are never validated for you — a missing key surfaces at the exact line that reads it, often deep inside a prerender. Fail fast in one place at boot rather than in fifty call sites.

When you are debugging a load, print key names rather than values, so the diagnostic itself does not become a leak:

node -e "const {loadEnvConfig}=require('@next/env');loadEnvConfig(process.cwd());\
console.log(Object.keys(process.env).filter(k=>/^(DATABASE|STRIPE|SESSION)/.test(k)).sort())"
# [ 'DATABASE_URL', 'SESSION_SECRET', 'STRIPE_SECRET_KEY' ]

An empty list means you are looking in the wrong directory (the loader uses process.cwd(), not the file's location), and a key present but pointing at localhost in production means the wrong file won the precedence contest. Also note that Next.js itself supplies a few variables — NODE_ENV, NEXT_RUNTIME, and the telemetry flag — so a grep of your own files will not show where every name in process.env came from.

The order above tells you which file wins locally. Throttling Abuse at the Edge already covered protecting the request path; here the question is which values every request runs with — and the next chapter's trap is what happens the moment a value crosses into browser JavaScript.

Prefixing a variable with NEXT_PUBLIC_ changes three things at once: who may read it, when its value is frozen, and whether changing it needs a rebuild. Non-prefixed variables live only in the Node runtime. Prefixed ones are replaced with a hard-coded string during next build, not read at runtime by the browser.

Prove it in thirty seconds:

echo 'NEXT_PUBLIC_ANALYTICS_ID=abcdefghijk' >> .env
npm run build
grep -R "abcdefghijk" .next/static | head -3
# .next/static/chunks/8f3c21...js:setupAnalytics("abcdefghijk")

That literal string ships to every visitor. It is the correct mechanism for publishable values — analytics IDs, public API bases, feature-flag names — and it is the reason a secret must never carry the NEXT_PUBLIC_ prefix. Access control in components, if (process.env.NODE_ENV !== 'production') guards, and "only used in one place" do not hide anything: anything inlined is published with the app.

Three consequences decide real bugs:

1. Build-frozen. After next build, editing the value does nothing. Build one Docker image and promote it through staging and production, and every NEXT_PUBLIC_ value is whatever the build machine saw. When a public value genuinely differs per environment, fetch it at runtime from an API instead of faking it with build args.
2. Only static lookups are inlined. process.env.NEXT_PUBLIC_ANALYTICS_ID is replaced. A computed key — const k = 'NEXT_PUBLIC_X'; process.env[k] — or destructuring the whole object first (const env = process.env; env.NEXT_PUBLIC_X) cannot be analyzed by the bundler, so the browser receives undefined and you get a runtime failure that no type checker catches.
3. Server-side reads follow different rules. In the Node runtime, process.env.STRIPE_SECRET_KEY is read from the real environment when the request executes, so dynamic rendering, route handlers, server actions, and middleware all pick up the current environment's value with no rebuild. The exception is a page prerendered at next build: that module code runs during the build, and anything it renders into HTML comes from the build machine. Reading a secret inside a statically generated page is how a key ends up in a cached HTML file.

A third path exists in next.config.mjs:

const nextConfig = {
  env: { PUBLIC_BUCKET: 'my-bucket' }, // inlined into server AND client output
}
export default nextConfig

It does not bypass the rule — those values are baked into both bundles at build time, so treat them as build inputs, not as secrets, and never place a token there "because it is not prefixed".

A mixed case comes up constantly: the client needs a value that does differ per environment. Solve it with a server route that reads at runtime and let the client ask for it — no rebuild, no secret shipped:

// app/api/config/route.ts — runs on the server, reads live env
export const dynamic = 'force-dynamic'
export async function GET() {
  return Response.json({ apiBase: process.env.PUBLIC_API_BASE })
}

The test an interviewer may ask you to perform on the spot is the grep from the first half of this chapter: build, search .next/static for the value, and show it in the chunk. If you cannot find it there, the browser does not have it — that is the only reliable check, because reading your own source tells you nothing about what the bundler substituted.

The working rule to carry forward: NEXT_PUBLIC_* = public and frozen at build; plain process.env = server-side and read at request time; prerendered HTML = whatever the build machine had. Where each environment keeps its own set of those values is the operational half of this topic, and it is exactly what Deploying to a Node Platform puts side by side.

Security reports that a Stripe key appeared in a CI log. You revoke it in the dashboard, deploy nothing, and production keeps working — or dies, depending on where that key lived. Rotation is the fastest way to discover whether a value was build-time or runtime, so design for it before the incident.

The third row is the one to aim for: a value injected at runtime means rotating a secret is an environment change plus a rolling restart, with no new build, no new artifact, and no window where old code runs with the wrong key. Every platform gives you a place to put these; they differ only in shape:

The failure this prevents: each environment gets its own variable set, so a dev key can never touch production. Written out, a storefront's sets look like this:

Note the pattern: pointers (DATABASE_URL) must differ outright between staging and production, credentials differ by value and kind, and only genuinely public values are allowed to repeat. Two concrete guards make that real. Staging must have a different DATABASE_URL than production — separate databases, not separate prefixes on the same cluster — and a live-versus-test mismatch should refuse to boot:

// instrumentation.ts — register() runs once, before traffic is accepted
export async function register() {
  if (process.env.NODE_ENV === 'production' && !process.env.STRIPE_SECRET_KEY?.startsWith('sk_live_')) {
    throw new Error('STRIPE_SECRET_KEY is a test key — refusing to start in production')
  }
}

A throw inside register() keeps the server from ever becoming ready, so your supervisor or load balancer leaves the previous healthy instance in service instead of routing buyers to a store that will decline every card.

Two hygiene rules round it out. Log configuration names, never values: an allowlisted redaction (pino's redact option) beats grepping output for sk_live_, and dumping process.env inside an error handler ships your whole secret set to an error tracker. And keep .env*.local out of git forever — platform stores and secret managers are the only homes for real keys.

You now know which values freeze at build and which survive to request time. Deploying to a Node Platform shows how Vercel, Netlify, Fly, and Railway each decide that for you.