env-sentinel 🛡️

Validate, coerce, and guard your environment variables at startup.

env-sentinel ensures that your application fails fast and gracefully if required environment variables are missing, of the wrong type, or fail validation. It also provides type coercion (e.g., '3000' → 3000), defaults, and automatic .env.example generation.

Installation

npm install env-sentinel

Usage

const { sentinel } = require('env-sentinel');

const env = sentinel({
  PORT: { type: 'port', default: 3000, description: 'HTTP server port' },
  NODE_ENV: { type: 'string', enum: ['development', 'production', 'test'], default: 'development' },
  DATABASE_URL: { type: 'url', description: 'PostgreSQL connection string' },
  API_KEY: { type: 'string', validate: v => v.startsWith('sk-') || 'Must be a valid secret key' },
});

console.log(`Server starting on port ${env.PORT}`);
// `env` is fully typed, coerced, and guaranteed to be valid at this point.

Features

• Coercion: Automatically converts string values to number, boolean, integer, json, url, etc.
• Validation: Supports enum, regex, min/max ranges, and custom validation functions.
• Missing Variable Checks: Throws descriptive errors when required variables are missing.
• Fail Fast: Optionally throws, logs, or silently ignores validation errors.
• Example Generation: Easily generate a .env.example file based on your schema.
• TypeScript Support: First-class TS definitions provided out of the box.

API

sentinel(schema, [source], [options])

Validates and returns your environment variables.

• schema: An object detailing your variable constraints.
• source: The environment object to read from (defaults to process.env).
• options:
  • strict (boolean): Warns about variables found in the source that aren't in the schema.
  • prefix (string): Filters and strips a specific prefix (like APP_) from variables.
  • onError: 'throw' (default), 'log', or 'silent'.

Schema Types

Available core types for coercion: string, number, integer, boolean, url, email, json, port.

Field Rule Properties

When defining fields as an object instead of a string, you have access to:

• type: One of the types above.
• required: If the variable must be present (defaults to true).
• default: Fallback value if missing.
• enum: Array of allowed values.
• regex: Regular expression to match string values against.
• min, max: Range boundaries for numeric values.
• validate: Custom validation function (value) => boolean | string | void. Return string for custom error message.
• description: Used in error messages and example generation.
• example: Provide explicit sample value for auto-generated config.

generateExample(schema, [options])

Returns a string that you can write to a .env.example file.

check(schema, [source], [options])

CI-friendly helper that returns 0 if the environment is valid and 1 if invalid. Does not throw exceptions, but instead prints a formatted error report directly to the console.

License

MIT