🛡 envguard-pro

Runtime environment variable validation — catches missing or malformed configuration before your application crashes in production.

Features

• ⚡ Zero-Config Validation: Automatically infers type schemas from your .env.example file — no manual schema code needed.
• 🎨 Beautiful Terminal Reports: Prints clear, color-coded error reports on validation failure.
• ⚙️ CLI Tooling: Validate .env files, initialize templates, and generate TS types or Zod schemas.
• 📦 Dual ESM/CJS Support: Packaged for modern import and legacy require environments.
• 🛡 Fail-Safe Startup: Throws on startup in production to prevent running with broken config.
• 🔍 Batch Error Reporting: Collects all errors at once — no fixing one at a time.

Installation

npm install envguard-pro

If you plan to use the CLI, you can also run it directly without installing:

npx envguard-pro --help

Quick Start

Add this to the very top of your application entry point (index.js or app.ts):

import { validateEnv } from "envguard-pro";

// Validates process.env against .env.example at startup
validateEnv();

Your .env.example is all you need — no schema to write separately:

# .env.example
PORT=3000
DATABASE_URL=                        # required, type: url
NODE_ENV=development                 # enum: development, production, staging
ADMIN_EMAIL=                         # required, type: email
API_KEY=                             # optional

Programmatic Usage

Basic

import { validateEnv } from "envguard-pro";

validateEnv();

With Options

import { validateEnv } from "envguard-pro";

validateEnv({
  // Path to your .env.example file (default: '.env.example')
  examplePath: "./custom/.env.example",

  // Print errors but don't throw — useful for warnings-only mode (default: true)
  throwOnError: false,
});

Command Line Interface (CLI)

Help

npx envguard-pro --help

1. Check an environment file

Validates your local .env against the .env.example schema:

npx envguard-pro check --env .env --example .env.example

Add --json to get structured output for CI/CD pipelines:

npx envguard-pro check --env .env --example .env.example --json

Exits with code 1 on failure, 0 on success — works natively with GitHub Actions and any CI tool.

2. Initialize a template

Generates a starter .env.example file in the current directory:

npx envguard-pro init

3. Generate code

Generates TypeScript types and/or a Zod schema directly from your .env.example:

npx envguard-pro generate --types --zod --outdir ./src

| Flag | Output file | What it does | | :-------- | :----------- | :------------------------------------------- | | --types | env.d.ts | Declares types on global process.env | | --zod | env.zod.ts | Exports a ready-to-use Zod validation schema |

Schema & Type Inference

envguard-pro infers validation rules from both the example value and inline comment annotations in your .env.example:

| Type | Format in .env.example | Valid values | | :----------- | :----------------------------------------------------- | :------------------------------------------------- | | Number | PORT=3000 | Any numeric string e.g. 8080, -45 | | Boolean | DEBUG=true | true or false (case-insensitive) | | URL | DATABASE_URL= # type: url | Complete URL with protocol e.g. https://db.com | | Email | ADMIN_EMAIL= # type: email | Valid email address format | | Enum | NODE_ENV=development # enum: development, production | Must match one of the comma-separated values | | Optional | API_KEY= # optional | Can be omitted or empty | | Required | SECRET_KEY= | Must be present — default for all unannotated keys |

How It Compares

| Feature | envguard-pro | envalid | t3-env | dotenv | | :--------------------------------- | :----------: | :-----: | :----: | :----: | | Zero-config (reads .env.example) | ✅ | ❌ | ❌ | ❌ | | Auto type inference | ✅ | ❌ | ❌ | ❌ | | Batch error reporting | ✅ | ✅ | ✅ | ❌ | | Zod schema generation | ✅ | ❌ | ❌ | ❌ | | TypeScript type generation | ✅ | ❌ | ❌ | ❌ | | CLI tooling | ✅ | ❌ | ❌ | ❌ | | CI/CD JSON output | ✅ | ❌ | ❌ | ❌ | | Dual ESM + CJS | ✅ | ✅ | ✅ | ✅ | | No schema duplication | ✅ | ❌ | ❌ | ❌ |

License

MIT © Rishima