envprowl

Catch missing or malformed environment variables before your app crashes on startup.

Most projects ship a .env.example, but nothing actually enforces that a developer's local .env matches it. envprowl closes that gap — one command, zero config, zero runtime dependencies.

$ envprowl
Errors (2)
  ✖ DATABASE_URL — Missing from .env (declared in .env.example)
  ✖ SERVER_PORT — Expected a valid port number (got "abc")
 
Warnings (1)
  ⚠ API_KEY — Present but empty
 
2 error(s) found.

Table of contents

• Why envprowl
• Installation
• Usage
• CI / pre-run integration
• Validators
• Configuration
• Environment-specific files
• JSON output
• Roadmap
• Contributing
• License

Why envprowl

Every team eventually hits the same failure mode: someone pulls the repo, forgets to fill in a required variable, and gets a confusing runtime error ten layers deep instead of a clear message up front. envprowl turns that into a five-second, human-readable check that runs before your app does:

• No forgotten variables. Anything declared in .env.example is verified present and non-empty in .env.
• No silent type mistakes. Common patterns (*_URL, *_PORT, IS_* / ENABLE_*) are checked against sane formats.
• No new dependencies. Built on Node's built-in fs and util modules only — nothing to audit, nothing to update.
• CI-friendly. Exits non-zero on error, so it fails builds the same way a linter would.

Installation

npm install --save-dev envprowl

Or run it without installing, via npx:

npx envprowl

Requires Node.js 18 or later.

Usage

envprowl                          # reads .env and .env.example from the cwd
envprowl --env .env.local         # point to a different actual-values file
envprowl --example .env.sample    # point to a different example/template file
envprowl --environment production # layer .env.production on top of .env
envprowl --config custom.json     # use a config file other than .envprowlrc
envprowl --json                   # machine-readable output
envprowl --help                   # show all options

Exit codes:

| Code | Meaning | | ---- | --------------------------------- | | 0 | No errors (warnings may still print) | | 1 | One or more errors found |

CI / pre-run integration

Because envprowl exits non-zero on error, it drops cleanly into existing scripts and pipelines.

npm scripts:

{
  "scripts": {
    "predev": "envprowl",
    "prestart": "envprowl",
    "dev": "next dev",
    "start": "node server.js"
  }
}

GitHub Actions:

- name: Validate environment configuration
  run: npx envprowl --example .env.example --env .env.ci

Validators

envprowl ships with four validators enabled by default. Each one is a small, independent module — see Contributing to add your own.

| Validator | Severity | Checks | | ------------ | ---------------- | --------------------------------------------------------------------------------------------- | | required | Error / Warning | Every key in .env.example exists in .env; empty values are flagged as warnings | | format | Error / Warning | *_URL / *_URI look like URLs, *_PORT is a valid port number, IS_* / ENABLE_* are boolean-like | | secrets | Error / Warning | Values matching common leaked-secret formats (Stripe, GitHub, AWS, Slack, PEM keys). A match in .env.example is an error (that file is usually committed); a match in .env is a warning | | undeclared | Warning | Keys present in .env but never declared in .env.example |

Configuration

Drop a .envprowlrc (JSON) in your project root to customize behavior — see .envprowlrc.example:

{
  "ignore": ["LEGACY_FEATURE_FLAG"],
  "rules": {
    "undeclared": "off",
    "format": "error"
  }
}

• ignore — keys to skip entirely, across every validator.
• rules — per-validator severity override. Set a validator to "error", "warning", or "off". Point to a config file elsewhere with --config path/to/file.

Environment-specific files

Layer environment-specific overrides on top of your base .env with --environment <name>, which merges in .env.<name> if it exists (values there win over the base file):

envprowl --environment production   # merges .env + .env.production

JSON output

For CI systems or scripts that want structured output instead of colored text, pass --json:

$ envprowl --json
{
  "ok": false,
  "errorCount": 1,
  "warningCount": 1,
  "issues": [
    {
      "key": "DATABASE_URL",
      "message": "Missing from .env (declared in .env.example)",
      "severity": "error",
      "validator": "required"
    }
  ]
}

Roadmap

Not yet built — contributions very welcome:

• [ ] Suggest a fix inline (e.g. auto-generate a .env stub from .env.example)
• [ ] Editor/IDE integration (VS Code extension surfacing issues inline)
• [ ] Plugin system for organization-specific validators
• [ ] Support for .env files with multiline values Have an idea that's not listed? Open an issue — "don't quite fit the existing validators" is exactly the kind of thing this project wants to hear about.

Contributing

Issues labeled good first issue are scoped to be approachable in a single sitting. CONTRIBUTING.md covers local setup, project structure, and a walkthrough for adding a new validator.

License

MIT