envcheck

Validate your .env before your app starts. One clear list of what's wrong — instead of a cryptic crash three files deep the first time a missing variable actually gets used. Zero dependencies.

The problem

An app boots fine locally, then breaks in staging because DATABASE_URL was never set there. The error that surfaces isn't "DATABASE_URL is missing" — it's a stack trace from deep inside a database driver, or worse, a silent undefined that only breaks something three requests later. Every backend stack hits this, constantly.

envcheck checks everything up front, at boot, and tells you exactly what's wrong before your app does anything else.

Install

npm install --save-dev envcheck

Or run it without installing:

npx envcheck validate

Quick start

1. Generate a schema from your current .env:

npx envcheck init

This scans your .env, guesses a reasonable type for each variable (string, number, port, boolean, url, email), and writes envcheck.config.json. Review it — the type guesses are a starting point, not gospel.

2. Validate anytime:

npx envcheck validate

✗ 3 problem(s) found:

  - PORT: 99999 is outside the valid port range (1-65535)
  - DEBUG: "notabool" is not a valid boolean (use true/false)
  - ADMIN_EMAIL is missing

3. Check it at app boot, not just from the CLI:

// at the very top of your app's entry file
const { validateOrExit } = require('envcheck');
const env = validateOrExit();

// env.PORT is a real number, env.DEBUG is a real boolean —
// already validated and type-coerced, not raw strings
app.listen(env.PORT);

If validation fails, validateOrExit() prints every problem and exits the process immediately — the app never starts in a broken state.

4. Keep .env.example in sync automatically:

npx envcheck example

Generates .env.example straight from your schema, including comments for descriptions and allowed enum values. No more onboarding docs going stale.

Schema format

envcheck.config.json:

{
  "DATABASE_URL": { "type": "url", "required": true, "description": "Postgres connection string" },
  "PORT": { "type": "port", "required": false, "default": 3000 },
  "NODE_ENV": { "type": "enum", "values": ["development", "production", "test"], "required": true },
  "DEBUG": { "type": "boolean", "required": false, "default": false },
  "ADMIN_EMAIL": { "type": "email", "required": true }
}

Supported types: string, number, integer, port, boolean, url, email, json, enum (with a values array)

Fields per variable:

• type — required
• required — defaults to true; set false if there's a default
• default — used when the variable is missing or empty
• values — required for type: "enum"
• description — shown in error messages and in generated .env.example comments

CLI reference

envcheck init                    Scaffold envcheck.config.json from your current .env
envcheck validate                 Validate against the schema
  --env-file <path>               (default: .env)
  --schema <path>                 (default: envcheck.config.json)
envcheck example                  Generate .env.example from the schema
  --schema <path>
  --out <path>                    (default: .env.example)

Exit code 0 when valid, 1 when problems are found — safe to use directly in CI. A ready-to-use workflow is included at .github/workflows/envcheck.yml.

Why this exists

Most config validation is either bolted onto a framework you may not be using, or skipped entirely until something breaks in production. envcheck is one small, standalone tool that does this one job — no framework lock-in, no dependencies, works with any Node.js backend.

Built by Cybergeon Technologies.

License

MIT © Cybergeon Technologies — see LICENSE.