Build-Time vs Runtime Environment Variables

A build-time environment variable is read once — when your bundler or compiler runs — and its value is frozen into the artifact; a runtime variable is read fresh from process.env every time the program starts. Confuse the two and a VITE_ or NEXT_PUBLIC_ value meant for staging ships hard-coded into production, sitting in plain text inside every JavaScript bundle and surviving in CDN caches until the next rebuild. Next.js states the trap in its own docs: after next build, "your app will no longer respond to changes to these environment variables." The mechanism is the same across Vite, webpack, esbuild, and Docker ARG — only the prefix and the flag change.

What is the difference between build-time and runtime environment variables?

It comes down to when the value is resolved. A build-time variable is consumed by a tool that produces an artifact — a JavaScript bundle, a container image, a compiled binary. The tool reads the variable from its own environment, substitutes the value directly into the output, and the variable name is gone by the time the artifact exists. A runtime variable is never touched by the build; it is read by the running program from the environment it was launched in, so the same artifact behaves differently depending on where you start it.

The 12-Factor App calls this the build/release/run separation: the build stage turns code into an executable bundle, and config is supposed to enter at the release or run stage so one build can serve every environment. Build-time injection deliberately breaks that rule — it trades flexibility for the ability to tree-shake and inline constants. That trade is correct for genuinely public, build-invariant values and wrong for everything else.

How do you inject environment variables into the build process?

You set the variable in the environment the build command runs in. The detail that trips people up: bundlers only expose variables that carry a public prefix, while Docker needs an explicit ARG declaration. Three mechanisms cover almost every stack.

Bundlers read prefixed variables present at build time and inline them. The Vite env guide and the Next.js env guide cover the prefix rules in depth:

# Vite — exposes VITE_* on import.meta.env, inlined at build
VITE_API_URL=https://api.example.com vite build

# Next.js — inlines NEXT_PUBLIC_* into the client bundle at next build
NEXT_PUBLIC_API_URL=https://api.example.com next build

# esbuild — explicit text substitution via --define
esbuild app.js --bundle --define:process.env.NODE_ENV='"production"'

webpack does the same thing through DefinePlugin, which performs a literal text replacement — wrap values in JSON.stringify or the substitution produces a bare identifier instead of a string:

// webpack.config.js
const webpack = require('webpack');

module.exports = {
  plugins: [
    new webpack.DefinePlugin({
      'process.env.API_URL': JSON.stringify(process.env.API_URL),
    }),
  ],
};

Docker passes values in with --build-arg, received by an ARG in the Dockerfile. The Docker env guide details the ARG vs ENV layering:

# Dockerfile
ARG VITE_API_URL
RUN VITE_API_URL=$VITE_API_URL npm run build

# build command
docker build --build-arg VITE_API_URL=https://api.example.com -t web .

In CI, the same idea is just an env: block on the build step — the value lives only for the duration of the build:

# GitHub Actions
- name: Build
  run: npm run build
  env:
    VITE_API_URL: ${{ vars.API_URL }}

Which tools freeze env vars at build time vs read them at runtime?

The single most useful thing to memorize is which side of the line each tool sits on. Anything in the build-time column ships its value inside the artifact; anything in the runtime column reads fresh on each start.

Why did my secret end up in the JavaScript bundle?

Because it was referenced in code the bundler inlines. The prefix on a client variable — VITE_, NEXT_PUBLIC_, REACT_APP_ — is a publication marker, not a protection: it tells the bundler "copy this value verbatim into the shipped JavaScript." Once that happens, the value is in every user's browser and your CDN cache, and a rebuild is the only way to remove it. Rotate any key that leaked this way; it is already compromised.

Detection is one command. Build, then search the output directory for the literal value:

npm run build
grep -rF "sk_live_" dist/   # or build/, .next/, out/ — your output dir

# anything printed is baked into the artifact and shipped to users

The Docker side has the same hazard with a different surface. ARG and ENV values are stored in the image and visible to anyone who runs docker history. Docker's own docs are blunt: "Build arguments and environment variables are inappropriate for passing secrets to your build, because they persist in the final image." The fix is BuildKit secret mounts, which expose the value only for one RUN and leave nothing behind:

# syntax=docker/dockerfile:1
FROM node:24
RUN --mount=type=secret,id=npmtoken \
    NPM_TOKEN=$(cat /run/secrets/npmtoken) npm ci

# build command
docker build --secret id=npmtoken,src=$HOME/.npm_token -t web .

For the full threat model — what counts as a secret, where leaked keys surface, and how to rotate — see the environment variables security guide.

When should you read env vars at runtime instead?

Build-time injection is the wrong default whenever the value is not both public and fixed for the life of the artifact. Reach for runtime config in these cases:

• Build once, deploy to many environments — promoting one immutable image or bundle through staging and production. Build-time values freeze to whatever was set during that single build, so you would have to rebuild per environment. Inject at container start instead (an entrypoint script that writes window.__CONFIG__ or a config.json the app fetches on boot).
• Secrets and rotating credentials — API keys, database URLs, signing keys. Read them at runtime on a server you control so a rotation does not require a rebuild and the value never reaches client code.
• Per-tenant or per-request configuration — anything that varies by user, region, or request cannot be a single build-time constant. It must be read at runtime.

Opinionated rule of thumb: prefer runtime config for anything that differs per environment or rotates, and reserve build-time inlining for values that are genuinely public and identical everywhere — a feature-flag default, a public analytics ID, a git SHA stamped into the build. The Docker, CI & Kubernetes env tips guide covers the runtime-injection idioms per platform.

Frequently Asked Questions

References

• Next.js docs — Environment Variables — documents NEXT_PUBLIC_ build-time inlining and the runtime-read pattern with connection()
• Vite docs — Env Variables and Modes — the VITE_ prefix and static replacement at build time
• webpack docs — DefinePlugin — compile-time variable replacement, including process.env
• esbuild docs — define — build-time substitution of identifiers and expressions
• Docker docs — Build secrets — why ARG/ENV persist in the image and how --mount=type=secret avoids it
• The Twelve-Factor App — Build, release, run — the conceptual basis for keeping config out of the build stage