The .env file that quietly diverges from production
Local config drifts from staging, which drifts from production, and the .env.example file drifts from all three. Nobody notices until a deploy fails on a variable that's been missing for months.
Hammad Iqbal
Software Engineer
Every project starts with a clean `.env.example` that matches reality. Six months and a dozen feature branches later, half the team has local variables nobody documented, staging has one manually patched in through a dashboard after an incident, and production is the only environment anyone's actually sure about — until the next deploy proves otherwise.
- `.env.example` is documentation that nobody's forced to keep updated.
- A missing env var should fail loudly at boot, not three requests into runtime.
- Secrets and ordinary config are two different problems wearing the same file.
The example file rots the moment it isn't enforced
Adding a new environment variable and updating `.env.example` are two separate steps, and only one of them is required for the feature to work on your machine. Without something checking that the two stay in sync, `.env.example` becomes a snapshot of the config from whenever someone last remembered to touch it — useful as a rough guide, not trustworthy as documentation.
Fail at startup, not at the first request that needs the variable
A missing `STRIPE_SECRET_KEY` should crash the app the moment it boots, with an error that names the variable. What it shouldn't do is boot cleanly and then throw an opaque undefined error the first time someone hits checkout — by then it's a production incident instead of a deploy that never went out. A small schema validated against `process.env` on startup, with something like `zod`, turns a runtime mystery into a startup log line.
- Validate all required env vars against a schema at boot
- Fail with the variable's name in the error, not a generic 'config invalid'
- Keep the schema and `.env.example` generated from the same source, so they can't drift
Secrets belong in a vault, not a config value
An API key and a feature flag both live in `.env`, but they're not the same kind of risk — one leaking in a screenshot or a log line is a genuine incident, the other is a shrug. Treating both as identical usually means the secret gets the feature flag's level of care: committed by accident once, pasted into a Slack thread for debugging, or left in a `.env.local` that somehow makes it into a screen share.
Validate config at boot and treat secrets as a different category from ordinary settings. The failure mode you're avoiding is a debugging session at 2am, not a comment in code review.
Have a project this kind of thinking applies to?
Tell me what you're building — I read every message myself.