Environment Variables & Config (.env, YAML)
You cloned a project, ran it, and it died with Error: DATABASE_URL is not set. Or you opened a repo
and found a file called config.yaml, a file called .env.example, and a warning in the README saying
never commit your .env — with no explanation of why. None of this was ever taught to you; it just
showed up in every project and you were expected to already know.
This guide makes it knowable. By the end you'll understand what a config file actually does, why your settings live outside your code in the first place, what an environment variable really is, and how the common config formats (YAML and friends) work — including the indentation trap in YAML that bites everyone exactly once.
How to read this
- Just need to get a project running? Skim Phase 2: Environment Variables & .env Files
— it covers reading variables and the
.envfile most projects expect. - Want it to finally make sense? Read in order. Each phase builds on the one before, starting with the mental model that makes the rest obvious.
The phases
- Why Config Lives Outside Code — the same app runs on your laptop, on staging, and in production with different settings; config is how you separate what-changes-per-environment from the code itself.
- Environment Variables & .env Files — what an environment variable
actually is, how to read one from the shell and from code, and how
.envfiles make local development sane (and why you must never commit them). - Config Files: YAML & Friends — YAML, JSON, and TOML for structured config, the YAML indentation gotcha, and the precedence order that decides which setting wins.
Deeper material — how to store production secrets safely (vaults, encrypted secrets, cloud secret managers) — lives in its own guide: Secrets Management. This guide gets you to the point where you understand why secrets belong in config and out of Git.