Environment variables explained for beginners

What problem do they solve?

Two things need to change between your laptop and your live site: secrets, which must not be written into files, and settings, which differ per environment — a test payment key locally, a real one in production.

const apiKey = process.env.STRIPE_SECRET_KEY;
if (!apiKey) throw new Error("STRIPE_SECRET_KEY is not set");

The explicit check matters. Without it, an unset variable becomes `undefined`, the request goes out with no credential, and you get a confusing 401 instead of a clear message about configuration.

Which variables reach the browser?

Build tools only expose variables with a specific prefix to browser code — commonly `VITE_` or `NEXT_PUBLIC_`. Everything else stays on the server. That prefix is a decision, not a formality: prefixing a secret makes it public.

If you ever prefix a secret to 'make it work in the component', the real fix is to move that code to the server.

Why is my variable undefined?

1. 1Confirm it is set in the environment you are actually running — local, preview and production are separate lists.
2. 2Check the spelling exactly, including case. `API_KEY` and `Api_Key` are different variables.
3. 3Restart the dev server or redeploy. Most environments read variables at start-up, not per request.
4. 4For browser-visible values, confirm the required prefix is present and that you rebuilt after adding it.
5. 5Read the value inside the function that uses it, not at the top of the module, where it may be evaluated before the environment is ready.

Why does the build bake some values in?

Browser-visible variables are substituted into your JavaScript when the project is built. Changing one afterwards does nothing until you build again. Server-side variables are read while running, so changing one takes effect on the next restart.

This is why 'I added the variable and nothing changed' is almost always a missing rebuild for front-end values, and a missing restart for server values.

What does AI often get wrong here?

• Reading `process.env` at the top of a module, where the value can be undefined at import time.
• Inventing a variable name that does not match the one you actually created.
• Assuming a variable set locally exists in production too.
• Silently defaulting to an empty string instead of failing loudly.