Writing a Good .env.example

Your .env.example is the contract between your code and everyone who runs it. This page shows two versions of the same file. Both are valid, but the second one is what dotenv-diff suggests as a best practice for your team.

Minimal version

The bare minimum: every key your code uses, with empty or placeholder values.

This is enough for dotenv-diff to detect missing and unused variables — but a new contributor still has no idea what any of these keys are for, or where to get a value.

Documented version

The same file, written so it is easy to understand for new contributors to the team.

.env.example

# Database connection string for your Postgres database
DATABASE_URL=

# SMTP host for sending emails
SMTP_HOST=

# SMTP port for sending emails
SMTP_PORT=587

# Port for your application to listen on
PORT=3000

# Node environment (development, production, etc.)
# @optional
NODE_ENV=development

# Public API URL is used to call our backend
PUBLIC_API_URL=http://localhost:3000

# Temporary token for the partner API sandbox - ask the integrations team for a new one
# @expire 2027-03-31
PARTNER_API_TOKEN=

Every key above is documented, so this file passes dotenv-diff --comment-warnings.

Annotations

Two keys in the example carry an annotation as well:

NODE_ENV is marked @optional, so dotenv-diff does not report it as missing when you leave it out of your .env — the code has a sensible default for it.
PARTNER_API_TOKEN has an @expire date, so dotenv-diff warns you when the token is close to expiring — and fails the build when it has less than 7 days left.

Note that an annotation on its own is not documentation: the real comment above it is what makes the key documented.

Finding undocumented keys

Comment warnings are opt-in. Enable them to flag every .env.example key that has no documenting comment — either a # comment on the line directly above, or an inline # comment after the value.

Or enable it permanently in your config file:

Best Practices

Never commit real secrets — keep values empty or use obvious placeholders.
Keep safe defaults (ports, local URLs) so the project runs out of the box.
Explain why a key exists and where to get a value, not just what it is called.
Group related keys together and keep the order stable to keep diffs readable.
Mark keys with a code-level default as @optional.
Add @expire to every time-limited token or credential.