The .env.staging File Is the Local Dev Hack Nobody Talks About

The .env.example file is a lie. It's always six months out of date, missing three variables that were added quietly in November, and whoever wrote it used YOUR_API_KEY_HERE as a placeholder like you wouldn't notice. It is a form of documentation that exists to technically exist.

The move — and I'm annoyed I didn't think of it — is .env.staging.

Not a template. Not a hint. The actual staging config, minus the secrets, committed to the repo. When someone clones the project and wants to run it locally against real infrastructure, they copy .env.staging, drop in their credentials, and it works — because staging is already configured to do the thing they're trying to do. The variables are right. The URLs are real. The feature flags are set to something sensible.

The .env.example approach assumes your example stays current. It never does. The .env.staging approach uses the thing that's already being maintained — the staging deployment — as the source of truth for what a working config actually looks like. You're not writing documentation. You're pointing at evidence.

It's a small thing. It saves maybe twenty minutes of onboarding confusion per developer. But it also eliminates the specific flavor of despair that comes from staring at an empty value for REDIS_TLS_URL at 11am on your first day, trying to figure out if staging even has Redis, and whether anyone on Slack is going to answer before lunch.

They are not going to answer before lunch.