envward

Validate your .env against a typed schema before the app boots. A missing DATABASE_URL, a PORT=abc, a NODE_ENV=prodd typo — these don't fail loudly, they fail deep in startup with a cryptic stack trace, or worse, silently in production. envward checks the whole environment against a small schema up front and tells you exactly what's wrong, in one place. Zero dependencies, no network.

$ envward

.env — checked against env.schema.json

  ✗ API_KEY   missing — required string
  ✗ NODE_ENV  "prodd" is not one of: development, production, test
  ✗ PORT      70000 is above max 65535

3 problem(s), 3 key(s) valid

Exits non-zero when anything is invalid, so it drops straight into a boot script or CI step. Unlike a drift checker (which finds missing keys), envward validates the values: types, ranges, formats, and allowed sets.

Get started in one command

# Infer a starter schema from your existing .env, then edit it:
envward --init > env.schema.json

--init guesses a type for each key from its current value (8080 → int, https://… → url, true → bool, …) and marks them all required. Tighten it from there.

The schema

A plain JSON file (env.schema.json by default), one rule per key:

{
  "PORT":         { "type": "int", "required": true, "min": 1, "max": 65535 },
  "DATABASE_URL": { "type": "url", "required": true },
  "NODE_ENV":     { "type": "enum", "values": ["development", "production", "test"] },
  "DEBUG":        { "type": "bool" },
  "API_KEY":      { "type": "string", "required": true, "minLength": 16 },
  "ADMIN_EMAIL":  { "type": "email" }
}

| Type | Accepts | |------|---------| | string | anything; constraints: minLength, maxLength, pattern (regex) | | int | integer; constraints: min, max | | number | integer or float; constraints: min, max | | bool | true / false / 1 / 0 (case-insensitive) | | url | scheme://… | | email | [email protected] | | enum | one of values (required array) |

required defaults to false. An empty value (KEY=) counts as missing.

Usage

envward                              # validate .env against env.schema.json
envward --env .env.prod --schema prod.schema.json
envward --strict                     # also flag keys in .env not declared in the schema
envward --json                       # machine-readable
envward --init > env.schema.json     # scaffold a schema from the current .env

Options

| Flag | Effect | |------|--------| | --env <file> | .env file to check (default .env) | | --schema <file> | JSON schema file (default env.schema.json) | | --strict | Keys present in .env but absent from the schema are problems | | --init | Print a schema scaffold inferred from the .env | | --json | Emit { valid, problems, summary } as JSON | | --quiet | Print only the one-line summary | | -v, --version · -h, --help | |

Use it as a gate

# package.json: "prestart": "envward"   — refuse to boot with a broken .env
# CI:           envward --env .env.ci --strict

Exit codes

| Code | Meaning | |------|---------| | 0 | every key valid | | 1 | one or more validation problems | | 2 | error (missing/invalid schema, unreadable file) |

A validator should fail when validation fails, so envward exits 1 on problems by default — no flag needed.

Notes

• Same tool, two builds. A behavior-equivalent Python build is on PyPI (pip install envward); use whichever your stack already has.
• .env parsing strips a single pair of surrounding quotes and an optional export prefix. Inline comments after a value are not stripped — quote values that contain #.
• pattern is a regex matched in ASCII mode (\d = [0-9]) and as an unanchored search — wrap it in ^…$ to match the whole value. For identical results across both builds keep to a portable subset (avoid inline (?i) flags, lookbehind, and named groups, which differ between the JS and Python engines; a malformed pattern is reported as a schema error, exit 2).
• Numeric min/max are compared at 64-bit float precision — ample for config; keep bounds within ±2^53.

License

MIT