Why does changing an environment variable on a running server not change a value already inlined into the client bundle?

## Substitution, not lookup When a meta-framework prepares code for the browser, a read of a publicly marked environment variable is not compiled into "go and look this up later". It is **textually replaced** with the value the build machine had at that moment. A comparison like `flag === 'on'` becomes a comparison between two literals, and the optimiser is then free to decide the branch and delete the loser. The output is a static asset. Nothing in it is capable of asking a question at runtime, so there is no mechanism by which a later change could reach it. ## What the build freezes, step by step 1. The build process starts and inherits an environment from whatever launched it — a pipeline runner, a container, a developer's shell. 2. Client-bound modules are scanned; each read of a marked name is rewritten to a literal. 3. The optimiser folds constants, eliminates branches now provably dead, and minifies. 4. The result is hashed into filenames and written to the output directory. 5. Those exact bytes are uploaded, usually cached by a CDN, and cached again by browsers under a long-lived policy because the filename is content-hashed. Every step after (2) is operating on a value that has already stopped being a variable. ## Why the usual remedies do nothing | Action | Effect on an inlined client value | |---|---| | Edit the variable in the deployment's settings | None — the artifact is already written | | Restart or scale the server process | None — the new process re-reads the environment for *server* code only | | Redeploy the same build artifact | None — the same bytes are served again | | Purge the CDN cache | None — the origin still holds the same file | | Run a new build with the new value | The value changes, and filenames change with it | | Read the value on the server per request and pass it to the client at render | The value changes without a build, at the cost of carrying it in the response | The first four are where teams lose an afternoon, because every one of them is the correct remedy for a *server-side* configuration change and none of them touches a client one. ## The same variable, two different lifetimes A single name can be read on both sides of the seam, and it behaves differently on each: - **Server read** — evaluated when that code runs, so it reflects the environment of the currently running process. Change it and redeploy the process, and the next request sees the new value. - **Client read** — evaluated once, by the build, and shipped as a constant. Change it and you must rebuild. That difference is what makes "it works on the server but the browser shows the old value" such a common report. Both reads look identical in source. ## Diagnosing it - **Search the emitted files for the literal.** If the old value is sitting in a shipped chunk, the question is settled: it was inlined, and only a rebuild moves it. This is also the cheapest audit for values that should never have been there. - **Check what the build machine saw**, not what the server has. Pipelines routinely expose different variables to a build step and to a runtime step, and a value absent at build becomes an empty literal rather than an error. - **Watch for a value that changed only after the next unrelated deploy.** That is the signature of a rebuild picking it up, and it confirms the inlining path. ## What it means for environment promotion Because the value is frozen at build time, a bundle is implicitly built *for one environment*. Promoting the identical artifact from staging to production carries the staging values with it — which is why teams either build once per environment or deliberately keep environment-varying values off the inlined path and deliver them at render instead. Values that genuinely do not vary — a public identifier, a build stamp, a flag flipped only by release — are the ones that inline comfortably. ## A related trap: the value that was never there If the variable was undefined on the build machine, the substitution still happens; it just produces an empty literal. Nothing warns you at request time, because at request time there is nothing left to warn about. Validating required public names at the end of the build — assert they are non-empty, fail the build if not — converts a silent production defect into a pipeline failure.