# Environment variables are documented in .env.example

- **Pattern:** `ab-000674` (`code-maintainability.documentation.env-example`)
- **Severity:** high
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-000674
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-000674)

## Why it matters

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.

## Severity rationale

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.

## Remediation

Create `.env.example` in the project root with every variable the project uses, substituting real values with descriptive placeholders:

```bash
# 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).

## Detection

- **ID:** `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:
  ```bash
  # 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.

## External references

- iso-25010 maintainability.analysability
- ssdf PW.4

Taxons: code-quality, operational-readiness

HTML version: https://auditbuffet.com/patterns/ab-000674