What a good .env.example looks like
A .env.example (also called .env.sample or .env.template) lists every variable the app reads, with no real values. A new developer runs cp .env.example .env, fills in the blanks and the app starts. The generator produces the skeleton; a few minutes of editing turns it into documentation:
# ── App ───────────────────────────── NODE_ENV=development PORT=3000 # ── Database ──────────────────────── # Local: docker compose up db DATABASE_URL=postgres://app:app@localhost:5432/app # ── Auth ──────────────────────────── # Generate: openssl rand -base64 32 JWT_SECRET= # ── Stripe (test mode keys only) ──── # Dashboard > Developers > API keys STRIPE_SECRET_KEY=sk_test_ STRIPE_WEBHOOK_SECRET=whsec_
- Group keys under comment headings in the order the app needs them.
- Say where a value comes from: a dashboard path, a CLI command, or a teammate.
- Local-only defaults are fine: a localhost database URL with dummy credentials helps more than an empty value.
- Show the format with a prefix like
sk_test_orwhsec_so people paste the right key.
Keeping .env and .env.example in sync
Most "works on my machine" bugs come from a key that exists in one developer's .env but not in the template. Three ways to catch drift:
- Paste both files into the missing env detector to see keys that exist in one file but not the other.
- Use the ENV diff checker for a side-by-side view before a release.
- Fail CI when they differ, with a few lines of shell:
# keys used in .env but missing from .env.example
comm -23 <(grep -oE '^[A-Za-z_][A-Za-z0-9_]*' .env | sort -u) \
<(grep -oE '^[A-Za-z_][A-Za-z0-9_]*' .env.example | sort -u)Also make sure git can never pick up the real file. The guide how to hide .env from git covers .gitignore patterns and what to do if a secret was already committed.
.env.example vs .env.local vs .env.defaults
| File | Contains | Commit to git? |
|---|---|---|
.env.example | all keys, no secrets, maybe safe defaults | yes |
.env | real values for this machine | no |
.env.local | machine-specific overrides (Next.js, Vite) | no |
.env.development / .env.production | non-secret defaults per mode (Next.js, Vite) | yes, if no secrets |
.env.defaults | fallback values loaded by dotenv-defaults | yes |