Your .env.example Is Lying to You, Here's How to Fix It

Last month I cloned a project, copied .env.example to .env, and ran npm run dev. The app crashed with a confusing database error. Turns out the example file was missing DATABASE_URL — someone had added it to the actual code months ago but forgot to update the example 🤔. I spent close to 45 minutes digging through source to find every env var the app needed.

This isn't a one-off. It can happens in every project that maintains .env.example by hand.

The problem

.env.example is documentation, and like all documentation, it drifts. Here's what goes wrong:

People add env vars and forget to update the example. This is the most common one. You need a new API key, so you add STRIPE_SECRET_KEY to your code and your actual .env. The example never gets touched.