env-guard

Secure environment variable validation and loading for Node.js. Validates required vars, types, and provides fail-fast behavior with clear error messages.

Features

• Schema-based validation (string, number, boolean, port)
• Fail fast on missing or invalid vars
• Type-safe access to validated values
• Optional .env loading via loadEnv()
• No hardcoded defaults for secrets (configurable per var)
• Zero runtime dependencies beyond dotenv for .env loading

Install

npm install @alirezaaminzadeh/env-guard

Quick Start

import { loadEnv, validateEnvOrThrow } from '@alirezaaminzadeh/env-guard';

// Load .env into process.env (optional)
loadEnv();

// Validate and throw on failure
const env = validateEnvOrThrow({
  PORT: { required: true, type: 'port' },
  NODE_ENV: { required: false, default: 'development' },
  API_KEY: { required: true, type: 'string' },
});

console.log(env.PORT);    // number (e.g. 3000)
console.log(env.NODE_ENV); // string
console.log(env.API_KEY);  // string

API

loadEnv(options?)

Load environment variables from a .env file into process.env.

loadEnv();                    // Load from process.cwd()/.env
loadEnv({ path: '.env.local' });
loadEnv({ env: customObject }); // Use custom object instead of process.env

validateEnv(schema, envOverride?)

Validate env vars against a schema. Returns a result object.

const result = validateEnv({
  PORT: { required: true, type: 'port' },
  DEBUG: { required: false, type: 'boolean', default: false },
});

if (result.success) {
  console.log(result.env.PORT, result.env.DEBUG);
} else {
  console.error(result.errors);
}

validateEnvOrThrow(schema, envOverride?)

Same as validateEnv but throws on failure. Use for fail-fast at startup.

Schema

| Field | Type | Description | |-----------|-------------------|---------------------------------------| | required| boolean | If true, var must be present | | type | string \| number \| boolean \| port | Parse and validate type | | default | string \| number \| boolean | Used when optional and missing |

Supported Types

• string: Any non-empty string (default)
• number: Parsed as number; rejects NaN
• boolean: Accepts true/false, 1/0, yes/no (case-insensitive)
• port: Number between 1 and 65535

License

MIT