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

#typescript #node #devops #webdev

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.
People remove env vars and leave them in the example. New devs waste time setting up vars that aren't even used anymore.
Comments are minimal or nonexistent. A bare key like SMTP_HOST= tells you nothing. Is it a URL? An IP? A hostname? Good luck guessing.
No one knows what's optional vs required. New team members don't know if they can start without setting SENTRY_DSN or if the app will crash.

The manual workflow is: add a var to code → (hopefully) remember to add it to .env.example → (hopefully) write a comment. That's three places to update. It fails constantly.

The fix: generate it from your schema

If you define your env vars in a schema file, you can generate .env.example from that file. The schema is the source of truth, so the example can never drift.

Here's what I do with CtroEnv (but the principle applies to any schema-based approach):

// src/env.ts
import { defineEnv, string, number, pick } from "@ctroenv/core";

export const env = defineEnv({
  DATABASE_URL: string().url().describe("Full PostgreSQL connection string"),
  PORT: number().port().default(3000).describe("HTTP server port"),
  NODE_ENV: pick(["dev", "prod"] as const).describe("Runtime environment"),
  SENTRY_DSN: string()
    .optional()
    .describe("Sentry DSN for error tracking (optional)"),
  SMTP_HOST: string().describe("SMTP server hostname"),
  SMTP_PORT: number().port().default(587).describe("SMTP server port"),
});

Then run:

npx @ctroenv/cli generate

The output writes to .env.example automatically:

# DATABASE_URL (required)
# Full PostgreSQL connection string
DATABASE_URL=

# PORT (optional, defaults to 3000)
# HTTP server port
PORT=3000

# NODE_ENV (required)
# Runtime environment
# Allowed values: dev, prod
NODE_ENV=

# SENTRY_DSN (optional)
# Sentry DSN for error tracking (optional)
SENTRY_DSN=

# SMTP_HOST (required)
# SMTP server hostname
SMTP_HOST=

# SMTP_PORT (optional, defaults to 587)
# SMTP server port
SMTP_PORT=587

Compare this to the manual version that probably exists in your project right now:

DATABASE_URL=
PORT=3000
NODE_ENV=dev
SENTRY_DSN=
SMTP_HOST=
SMTP_PORT=587

The generated version tells you:

What each var is for (the .describe() text becomes a comment)
Whether it's required or optional
What the allowed values are (for pick validators)
What the default is

How it stays in sync

When you add a new env var, you add it to the schema. That's one place. The .env.example gets regenerated from the schema. It's impossible for them to disagree because the schema is the only thing you edit.

When you remove a var, it's also one edit. Next time someone runs npx ctroenv generate, the old var doesn't appear. No stale keys.

Bonus: this helps onboarding

A new developer cloning your repo can run:

npx @ctroenv/cli check

This compares their current .env against the schema and tells them exactly what's missing or wrong. No more "I think I set everything but it's still crashing."

Bonus: ENVIRONMENT.md generation

The same schema can generate full documentation:

npx @ctroenv/cli docs --format markdown

This produces an ENVIRONMENT.md file with a table of every env var, its type, whether it's required, its default, and its description. Stick it in your repo and link to it from your README.

What about other tools?

If you're using Zod, you can parse env vars with it, but generating .env.example from Zod schemas isn't built in. You'd need to write your own code to extract descriptions and defaults from Zod's ._def.

envalid has envalid.cleanEnv but no CLI-based generation. Same deal — you'd need a custom script.

t3-env doesn't support generation either.

That's actually what pushed me toward CtroEnv — I wanted npx ctroenv generate to just work.

Practical advice

Stop editing .env.example directly. Even if you don't switch tools, make it a rule: edit the schema, regenerate the example.
Run generation as a pre-commit hook. Catch drift before it hits the repo.
Add descriptions. Future you will thank present you when you're debugging a production issue and need to remember what STRIPE_WEBHOOK_SECRET is for.
Run check in CI. Fail the build if someone's .env doesn't match the schema.