env-guard — Validate Environment Variables Before Deploy

Stop deploying with missing env vars. A zero-dependency CLI and library that validates .env files against .env.example or a JSON schema — one command catches them before your app does.

$ npx env-guard
✗ Environment validation failed:
  • DATABASE_URL: Missing variable
  • API_KEY: Missing variable

Validate .env files against .env.example or a JSON schema. CLI + library. Zero dependencies.

Quick Start

# Zero config — checks .env against .env.example
npx env-guard

✓ All environment variables validated.

or when variables are missing:

✗ Environment validation failed:

  • DATABASE_URL: Missing variable
  • API_KEY: Missing variable

Install

npm install env-guard

CLI Usage

# Default: validate .env against .env.example
npx env-guard

# Custom paths
npx env-guard --env .env.local --example .env.template

# Validate against a JSON schema
npx env-guard --schema env-schema.json

| Flag | Description | Default | | ----------- | ------------------------- | -------------- | | --env | Path to .env file | .env | | --example | Path to .env.example file | .env.example | | --schema | Path to JSON schema file | (none) |

Exit code is 0 when valid, 1 when validation fails.

Library Usage

import { envGuard } from "env-guard";

const result = envGuard();

if (!result.valid) {
  console.error("Missing:", result.missing);
  console.error("Errors:", result.errors);
  process.exit(1);
}

With custom paths

const result = envGuard({
  envPath: ".env.local",
  examplePath: ".env.template",
});

With JSON schema

const result = envGuard({
  schemaPath: "env-schema.json",
});

JSON Schema Format

Create a JSON file where each key is an env variable name:

{
  "PORT": { "required": true, "pattern": "^\\d+$" },
  "NODE_ENV": { "enum": ["development", "production", "test"] },
  "DEBUG": { "required": false },
  "API_KEY": true,
  "OPTIONAL_VAR": false
}

| Rule | Type | Description | | ---------- | ---------- | ------------------------------------------------- | | required | boolean | Whether the variable must exist (default: true) | | pattern | string | Regex pattern the value must match | | enum | string[] | Allowed values | | true | — | Shorthand for { required: true } | | false | — | Shorthand for { required: false } |

API

envGuard(options?): ValidationResult

| Option | Type | Default | Description | | ------------- | -------- | ---------------- | -------------------- | | envPath | string | ".env" | Path to .env file | | examplePath | string | ".env.example" | Path to example file | | schemaPath | string | — | Path to JSON schema | | cwd | string | process.cwd() | Working directory |

ValidationResult

interface ValidationResult {
  valid: boolean;
  missing: string[];
  extra: string[];
  errors: ValidationError[];
}

validateAgainstExample(envVars, exampleVars): ValidationResult

Lower-level function for programmatic use with pre-parsed env maps.

validateAgainstSchema(envVars, schema): ValidationResult

Lower-level function for programmatic use with a schema object.

parseEnvFile(content): Map<string, string>

Parse a .env file string into a Map. Handles comments, quotes, empty lines.

Author

Ofer Shapira

License

MIT © Ofer Shapira