Learn

What Is an Environment Variable? A Plain-English Explanation

A value your app reads from its surroundings instead of from a line of code. Why it exists, and why a missing one can break a working build the moment it's deployed.

Published 3 September 2026 · Updated 26 September 2026 · 5 min read

AI Build South Africa
A fundamentals guide, written for someone whose AI agent reads and writes environment variables for them, not someone configuring a server by hand.

Quick answer

An environment variable is a named value your app reads from its surroundings, the "environment" it's running in, rather than from a line written directly into the code. It's how a secret like an API key reaches your app without that value ever sitting in a file anyone could open and read, and it's why a value can differ between your builder's own preview and wherever you actually deploy. You set one in your builder's or host's own settings, never by typing the value into the code.

Tools for this build

POPIA Compliance Checker

A readiness checklist for when your app starts storing people's personal information.

Custom Prompt Builder

Naming exactly which environment variable is missing, once you can tell.

PayFast Webhook Generator

Generates code that reads its secrets from environment variables, not hardcoded values.

The one-sentence version: supplied, not written in

Ordinary code has values baked directly into it: a page title, a button's colour, a number in a calculation. An environment variable is different on purpose. Instead of writing a value into the file, the code asks its surroundings for it at the moment it actually runs, and whatever's currently set there is what comes back. The same file can run against a completely different value depending on where it's running, your builder's own preview, a separate host you deployed to, without a single line of code changing.

Written into the code vs. read from the environment

A hardcoded value

Baked into the file itself:

Visible to anyone who opens it, same everywhere

An environment variable

Supplied separately, at runtime:

Never sits in the file, can differ by location

AI Build · aibuild.co.za

Why this exists: keeping a secret out of your own code

The main reason environment variables exist at all is secrecy. This site's own guide to why an API key can't live in the frontend covers what happens when a value ends up somewhere a visitor's browser can read it. An environment variable solves the equivalent problem for backend code: instead of typing a real API key or database password directly into a file that might get shared, screen-recorded or accidentally committed somewhere public, the code holds only the variable's name, and the actual value lives in your platform's own secrets panel, set once and referenced by name from then on.

Why your AI builder needs a real backend to keep one

An environment variable only stays a secret if it's read somewhere your visitor's browser never touches, which means it belongs in backend code, the same frontend/backend split our project-structure guide covers. An AI website builder that comes with a backend keeps a separate place for secrets, and its backend functions read each one from there by name. Setting a key there, rather than typing the value straight into a page or component, is what keeps the whole arrangement private.

Why "it worked in preview but broke once deployed" can come down to a missing environment variable

Your builder's preview and your live site are often separate environments, and a value set for one isn't always there for the other. A separate host you deploy to starts with none until you add them in its own settings. The code is identical in both places, which is why re-reading it doesn't find the fault: the value the code expects simply isn't there on the live site. Our guide to environment variables not working after deploy covers the five causes and how to tell them apart.

Not every environment variable is a secret

It's worth separating two different jobs environment variables do, since treating both identically causes its own confusion. Some genuinely need protecting: an API key, a database password, anything that causes real damage if a stranger sees it. Others are just configuration with nothing to hide, which environment a build thinks it's running in, or a public API's base URL that happens to differ between a test setup and production. The mechanism (a named value supplied at runtime) is the same either way; the question worth asking about any specific one is simply what happens if someone else sees this value, not whether it technically counts as "an environment variable."

Examples of environment variables

The names change from project to project, and your builder or host documents the ones it reads, but most projects end up with a handful like these:

  • SITE_URL: your site's own address, different in the preview and on the live site. Not a secret.
  • API_BASE_URL: where your app sends its requests, often a test address while you build and the real one once you go live. Not a secret.
  • MAPS_PUBLIC_KEY: a key a provider designed to be used in the page. Not a secret, but it belongs to your account.
  • PAYMENT_SECRET_KEY: the private key for taking payments. A secret: it stays in your backend and never appears in the page's code.
  • DATABASE_PASSWORD: what your backend uses to reach your data. A secret.

If you're not sure which of your own values are secrets, ask your AI to list every environment variable the project reads and say, for each one, whether it's safe for a visitor to see.

Where to go next

Not affiliated with the platforms we write about

AI Build South Africa is an independent resource. We're not endorsed by, or an official partner of, any AI website builder or hosting provider. We do participate in affiliate and referral programmes with some providers. See our Disclaimer for the full disclosure and our Terms of Service for the wider terms.

Frequently asked questions

What's the difference between an environment variable and an API key?

An API key is a piece of data. An environment variable is one way of supplying that data to your app without writing it into the code. Most API keys get stored as environment variables, but not every environment variable is a key or a secret, some are ordinary configuration with nothing to hide.

Why does my app work in the builder's preview but break once I deploy it somewhere else?

Check for a missing environment variable before you look at the code. The builder's own preview already has the values set; a separate host you deploy to doesn't automatically inherit them. The code is identical in both places, which is exactly why re-reading it doesn't find the fault, the value it's expecting simply isn't there yet.

Is every environment variable a secret I need to protect?

No. Some are genuinely sensitive, an API key, a database password. Others are ordinary configuration with nothing to hide, which environment a build is running in, or a public API's base URL that happens to differ between testing and production. Treat each one based on what happens if a stranger sees it, not by assuming every environment variable needs the same level of protection.

How do I set one in my AI website builder?

In your builder's or host's own settings, usually in an area called secrets or environment variables, never by typing the value into a page or component. Your backend code then reads the value by name. Where that area sits changes as builders update their screens, so check your builder's documentation for where it currently sits.

What happens if I forget to set an environment variable on a new host?

The specific feature depending on it fails, usually with a symptom that doesn't obviously point at a missing variable: a blank screen, a silent API failure, an unauthenticated request. This is how a working build can fail right after a deploy; our guide to a blank screen after deploying covers it in more detail.

Can I see the value of an environment variable once I've set it?

Often not, by design. Most platforms' secrets panels show a masked value or nothing at all once saved, specifically so a screen share or a shoulder-glance doesn't leak it. If you need to check a value is correct, re-enter it rather than expecting to read back what you typed before.

Is it an environment variable or an environmental variable?

The term is environment variable: the value comes from the environment a program runs in, such as your computer, a builder's preview or your live host. "Environmental variable" is a common slip for the same thing. In science it means something else, a factor like temperature or rainfall, so use "environment variable" when you ask your AI about it.

Related reading