Why I Stopped Maintaining .env.example by Hand

"You add DATABASE_URL to your code on Tuesday. You forget to add it to .env.example. Three weeks later, someone's production deploy fails because they copied .env.example and missed the new variable. The real problem: nothing tells you .env.example is missing a variable until something breaks. The stale .env.example is a silent bug."

"There are good tools in this space. dotenv-safe has 152,609 downloads last week. envalid has 478,131. They work - but they're all declaration-first: you maintain a list of required variables in a schema file, and the tool validates your environment against that list. The problem: maintaining the schema is the same work as maintaining .env.example."

"Every time you write process.env.DATABASE_URL in your code, you've implicitly declared that you need DATABASE_URL. That declaration is already there. The insight: the source code already knows which variables are required."

Node.js projects frequently fail when developers clone repositories and run npm install because .env.example files become outdated and miss newly added environment variables. Existing tools like dotenv-safe and envalid require manual schema maintenance, creating the same problem as maintaining .env.example files. These tools validate against declared schemas but don't solve the core discovery problem of identifying which variables the code actually needs. The solution leverages source code analysis to automatically detect all process.env references, eliminating the need for manual schema updates and preventing silent bugs that only surface weeks later in production environments.

Read at DEV Community