env-doctor

Diagnose environment variable issues in any Node.js project.

Scans your source code for process.env usage and compares it against your .env.example — surfacing missing documentation, undocumented variables, and unused entries.

✓ Documented and in use (20)
✗ Used in code but missing from .env.example (2)
⚠ In .env.example but not found in code (8)

Install

npm install -g env-doctor

Or run without installing:

npx env-doctor

Usage

Run in any Node.js project directory:

env-doctor

Or point it at a specific directory:

env-doctor ./backend

What it checks

| Status | Meaning | | -------- | ---------------------------------------------------------- | | ✓ Green | Variable is documented in .env.example and used in code | | ✗ Red | Variable is used in code but missing from .env.example | | ⚠ Yellow | Variable is in .env.example but not found in source code |

Red items are the most critical — they mean a new developer cloning your repo won't know they need that variable.

Supported file types

Scans .js, .ts, .jsx, .tsx, .mjs, and .cjs files.

Ignores node_modules, .git, dist, build, coverage, .next, and .nuxt.

Exit codes

| Code | Meaning | | ---- | ------------------------ | | 0 | No issues found | | 1 | One or more issues found |

Exit code 1 on issues makes it suitable for use in CI pipelines.

CI Usage

- name: Check environment variables
  run: npx env-doctor ./backend

Limitations

• Only detects process.env.VARIABLE_NAME syntax — variables accessed via a config object (e.g. config.dbPassword) won't be caught
• Does not validate variable values, only presence in .env.example

License

MIT — Kolt Adams, 2026