envalid

Validation for your environment variables

weekly downloads408K

versionv8.1.1

licenseMIT

categorytoolchain

.envdotenvenvenv varenvironmentenvironment variablevalidation

Overview

Envalid is a validation library for Node.js environment variables that enforces type safety and configuration completeness before your application starts. With over 400,000 weekly downloads, it's designed to catch configuration errors early by validating that all required environment variables exist and conform to expected types.

The library was created to solve a common production problem: applications failing at runtime due to missing or malformed environment variables. Instead of discovering these issues when code tries to access a missing PORT variable or parse an invalid database URL, Envalid fails fast at startup with clear error messages about what's wrong.

Envalid provides built-in validators for common types (strings, numbers, URLs, emails, JSON) and allows you to create custom validators for domain-specific requirements. The validated environment object is immutable, preventing accidental modifications during runtime. This approach treats environment configuration as executable documentation—developers can see exactly what variables an application expects by reading the validation schema.

The library is particularly valuable for teams working on microservices, containerized applications, or any Node.js project where configuration mistakes can lead to silent failures or difficult-to-debug runtime errors. It pairs naturally with dotenv for local development while providing the validation layer that dotenv lacks.

Quick Start

typescript

import { cleanEnv, str, port, url, email, bool, num, json } from 'envalid';
import dotenv from 'dotenv';

dotenv.config();

const env = cleanEnv(process.env, {
  NODE_ENV: str({ choices: ['development', 'test', 'production'] }),
  PORT: port({ default: 3000 }),
  DATABASE_URL: url(),
  REDIS_HOST: str({ default: 'localhost' }),
  REDIS_PORT: port({ default: 6379 }),
  API_KEY: str({ docs: 'Third-party API authentication key' }),
  ADMIN_EMAIL: email(),
  ENABLE_CACHE: bool({ default: false }),
  MAX_CONNECTIONS: num({ default: 10 }),
  FEATURE_FLAGS: json({ default: {} })
});

console.log(`Server starting on port ${env.PORT}`);
console.log(`Environment: ${env.NODE_ENV}`);
console.log(`Cache enabled: ${env.ENABLE_CACHE}`);

const dbConfig = {
  url: env.DATABASE_URL,
  maxConnections: env.MAX_CONNECTIONS
};

const redisConfig = {
  host: env.REDIS_HOST,
  port: env.REDIS_PORT
};

export { env };

Use Cases

Microservices configuration: Validate that each service has its required API keys, database URLs, and feature flags before starting, preventing partial deployments where services boot but can't communicate properly.

Multi-environment deployments: Ensure staging and production environments have all necessary variables defined with correct types, catching configuration drift between environments before deployment completes.

Database connection strings: Validate database URLs, port numbers, and connection pool settings are properly formatted integers and valid URLs, preventing runtime connection failures.

API integrations: Verify third-party API credentials, webhook URLs, and timeout values are present and correctly typed, especially when integrating multiple external services with different configuration requirements.

Feature flag management: Validate boolean feature flags and enum-based configuration options to ensure only valid values are used, preventing typos like 'tru' instead of 'true' from disabling features in production.

Pros & Cons

Pros

+Type safety catches configuration errors at startup rather than runtime, significantly reducing debugging time for environment-related issues
+Immutable environment object prevents accidental modifications and provides consistent access throughout application lifecycle
+Built-in validators cover common types (URL, email, port, JSON) and custom validators enable domain-specific validation logic
+Clear error messages with actionable feedback about which variables are missing or incorrectly formatted
+Works seamlessly with dotenv and other environment loading tools without requiring changes to existing workflows

Cons

−Adds startup overhead as all environment variables are validated before application begins running, though typically milliseconds
−Steeper learning curve compared to simple dotenv usage, requiring developers to understand validator syntax and options
−May feel overly prescriptive for small scripts or projects where environment configuration is minimal and rarely changes
−Custom error reporters require understanding Envalid's internal error structures to implement properly
−No built-in support for loading .env files—must be paired with dotenv or similar loader

Alternatives

joiv18.0.2

Object schema validation

validationschemavalidation

15.5M / week

zodv4.3.6

TypeScript-first schema declaration and validation library with static type inference

validationtypescriptschema

85.3M / week

Install

bash

npm install envalid

bash

pnpm add envalid

bash

bun add envalid

Overview

Quick Start

typescript

import { cleanEnv, str, port, url, email, bool, num, json } from 'envalid';
import dotenv from 'dotenv';

dotenv.config();

const env = cleanEnv(process.env, {
  NODE_ENV: str({ choices: ['development', 'test', 'production'] }),
  PORT: port({ default: 3000 }),
  DATABASE_URL: url(),
  REDIS_HOST: str({ default: 'localhost' }),
  REDIS_PORT: port({ default: 6379 }),
  API_KEY: str({ docs: 'Third-party API authentication key' }),
  ADMIN_EMAIL: email(),
  ENABLE_CACHE: bool({ default: false }),
  MAX_CONNECTIONS: num({ default: 10 }),
  FEATURE_FLAGS: json({ default: {} })
});

console.log(`Server starting on port ${env.PORT}`);
console.log(`Environment: ${env.NODE_ENV}`);
console.log(`Cache enabled: ${env.ENABLE_CACHE}`);

const dbConfig = {
  url: env.DATABASE_URL,
  maxConnections: env.MAX_CONNECTIONS
};

const redisConfig = {
  host: env.REDIS_HOST,
  port: env.REDIS_PORT
};

export { env };

Use Cases

Database connection strings: Validate database URLs, port numbers, and connection pool settings are properly formatted integers and valid URLs, preventing runtime connection failures.

Pros & Cons

Pros

+Type safety catches configuration errors at startup rather than runtime, significantly reducing debugging time for environment-related issues
+Immutable environment object prevents accidental modifications and provides consistent access throughout application lifecycle
+Built-in validators cover common types (URL, email, port, JSON) and custom validators enable domain-specific validation logic
+Clear error messages with actionable feedback about which variables are missing or incorrectly formatted
+Works seamlessly with dotenv and other environment loading tools without requiring changes to existing workflows

Cons

−Adds startup overhead as all environment variables are validated before application begins running, though typically milliseconds
−Steeper learning curve compared to simple dotenv usage, requiring developers to understand validator syntax and options
−May feel overly prescriptive for small scripts or projects where environment configuration is minimal and rarely changes
−Custom error reporters require understanding Envalid's internal error structures to implement properly
−No built-in support for loading .env files—must be paired with dotenv or similar loader