What is an environment variable? (and why your app has a .env file)

What it actually is

An environment variable is a named value that lives outside your code, in the environment your program runs in, not typed into a source file. Think of it like the settings a hotel front desk hands a guest: the room itself (your code) is the same template for everyone, but the thermostat setting, the wifi password and the checkout time come from outside, and can be different for every guest, every night.

In a real project, this usually means a .env file sitting in your project folder, full of lines like:

DATABASE_URL=postgres://user:pass@localhost:5432/mydb
STRIPE_SECRET_KEY=sk_live_51...

Your code never contains the actual database password or API key. Instead it says something like process.env.DATABASE_URL, and whatever is running the app (your laptop, a hosting platform, a teammate’s machine) fills in the real value at that moment. Same code, different values depending on where and how it’s run. That’s the whole idea.

Why your AI just did this

When your agent wires your app up to something external (a database, Stripe, an email API, OpenAI itself), it needs a secret credential to make that connection work. A careful agent won’t paste that credential straight into a component file. It’ll create or edit .env, add STRIPE_SECRET_KEY=... there, and reference it in code as process.env.STRIPE_SECRET_KEY.

It’s doing this for three reasons: a hardcoded key inside a .js or .py file gets committed to git the moment you push, which means it’s now public if your repo ever goes public (see exposed API keys); different environments need different values, your local database URL is not your production database URL; and it lets you rotate a key or swap a config value without changing a line of code, though on some platforms, including Vercel, you still need to redeploy for the new value to take effect.

You’ll often also see it add a .env.example file, same variable names, no real values, as a template for you or a teammate to fill in.

When you’ll run into it

• The app crashes with something like Missing STRIPE_SECRET_KEY or process.env.DATABASE_URL is undefined, usually a mismatched variable name, or the file didn’t get loaded.
• Your agent says “I’ve added your key to .env. Make sure it’s in .gitignore.”
• The app works perfectly on your machine, then breaks the moment you deploy to Vercel or Railway, because .env never leaves your laptop; you have to add the same keys separately in the hosting platform’s dashboard.
• The PATH case from the question above: PATH is itself an environment variable, a list of folders your operating system searches, in order, when you type a command name. Adding your script’s folder to PATH is editing that variable so your terminal can find and run it by name, instead of you typing the full file path every time.
• Running git status and seeing .env untracked (correct) versus git diff --staged showing .env about to be committed (stop, fix .gitignore first).

What to check

• .env is listed in .gitignore before you ever run git add. Confirm with cat .gitignore
• No real secret values sit inside any code file. Only process.env.SOME_KEY references
• Your hosting platform’s dashboard has the same variables set separately; local .env does not travel with a deploy
• Variable names match exactly (case-sensitive) between .env and wherever the code reads them
• If a key was ever committed to git history, treat it as burned. Regenerate it at the source, don’t just delete the line

Say it like a dev

Instead of: “put the password right in the file” Say: “add it as an environment variable in .env, don’t hardcode it”

Instead of: “why doesn’t it work after I put it online” Say: “did we set these environment variables on the hosting platform too, not just locally?”

Instead of: “hide my key so it’s safe” Say: “make sure this variable is gitignored and never printed to the console or logs”