Without .env.example, every new developer must read source code to discover which environment variables the project requires — and they will invariably miss some. The result is a broken local setup, a support request to the original author, or — worse — a developer who hard-codes credentials to get unstuck. ISO 25010 maintainability.analysability fails at the setup boundary. SSDF PW.4 requires documenting configuration requirements; an absent .env.example is a direct gap. Projects with Supabase, Stripe, and auth libraries typically have 8–15 required variables.
High because a missing `.env.example` makes the project impossible to set up without direct help, blocking every new contributor and deployment to a new environment.
Create .env.example in the project root with every variable the project uses, substituting real values with descriptive placeholders:
# Authentication
NEXTAUTH_SECRET=generate-with-openssl-rand-base64-32
NEXTAUTH_URL=http://localhost:3000
# Database
DATABASE_URL=postgresql://user:password@localhost:5432/myapp
# Stripe
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
Commit .env.example to git. Keep .env.local gitignored. Reference .env.example in README.md setup instructions (see the readme-exists check).
ID: code-maintainability.documentation.env-example
Severity: high
What to look for: Check for .env.example or .env.sample in the project root. If found, verify it documents the variables the project actually uses: scan source files and config files for process.env.VARIABLE_NAME references and check that each one appears in .env.example. If .env.example exists but is empty or significantly incomplete (more than 2 required env vars missing), that is a fail. The file should contain key names with either placeholder values or comments describing what each value is.
Pass criteria: Count all process.env.* references in source code and list all unique variable names. .env.example (or .env.sample) exists and documents all required environment variables the project uses. No more than 2 missing variables. Values are replaced with placeholders (e.g., STRIPE_SECRET_KEY=sk_... or DATABASE_URL=postgresql://user:password@host:port/db). Report the count: "X of Y environment variables documented in .env.example."
Fail criteria: No .env.example file found, OR the file exists but is missing more than 2 environment variables that appear in source code, OR the file contains no placeholder values (is completely empty or has only comments).
Cross-reference: For README documentation that should reference .env.example in setup instructions, see the readme-exists check in this audit.
Skip (N/A) when: The project uses no environment variables — no process.env.* references found in source code and no hosting-level environment config. Signal: no process.env references anywhere in source files.
Detail on fail: "No .env.example found. Source code references STRIPE_SECRET_KEY, DATABASE_URL, NEXTAUTH_SECRET, and NEXTAUTH_URL — none are documented for new developers." or ".env.example exists but is missing DATABASE_URL and STRIPE_WEBHOOK_SECRET which are required by the application."
Remediation: The .env.example file is how new team members (and your future self on a new machine) know what environment variables are needed to run the project. Without it, the setup process requires reading source code to discover what's required.
Create .env.example with every variable your project uses:
# Authentication
NEXTAUTH_SECRET=generate-with-openssl-rand-base64-32
NEXTAUTH_URL=http://localhost:3000
# Database
DATABASE_URL=postgresql://user:password@localhost:5432/myapp
# Stripe
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
Never put real credentials in .env.example — only placeholders. Commit .env.example to git; keep .env.local gitignored.