envalid
Environment variable validation library for Node.js. envalid validates and transforms process.env variables at startup — defining required variables, optional variables with defaults, type coercion (str, num, bool, url, email, port), and custom validators. Throws descriptive errors at startup if required variables are missing rather than silently failing at runtime. Essential for 12-factor app configuration.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Validates env vars but doesn't encrypt them. Ensure secrets aren't logged via error messages — envalid shows variable names not values in errors, which is safe.
⚡ Reliability
Best When
Any Node.js service that needs validated, typed environment configuration with clear startup errors for missing required variables.
Avoid When
You need configuration from multiple sources (files + env) or runtime configuration updates — use convict or config package.
Use Cases
- • Validate all required agent environment variables (API keys, database URLs, ports) at startup — fail fast with clear errors instead of cryptic runtime failures
- • Create type-safe environment configuration objects for agent services using envalid's cleanEnv() with TypeScript inference
- • Document agent environment variable requirements with descriptions that appear in validation error messages for operators
- • Apply defaults for optional agent configuration variables using envalid's default parameter — reduces deployment friction
- • Validate URL format, email format, and numeric ranges for agent configuration values at startup before any connections are made
Not For
- • Complex configuration management — envalid handles environment variables only; use convict or config for multi-source configuration (files, env, CLI args)
- • Runtime configuration updates — environment variables are read at startup; use a config service for dynamic configuration
- • Non-Node.js environments — envalid is specifically for process.env in Node.js
Interface
Authentication
No authentication — local configuration validation library.
Pricing
envalid is open source and free.
Agent Metadata
Known Gotchas
- ⚠ envalid uses strict mode by default — undeclared environment variables are stripped from the cleaned env object; access via process.env for undeclared vars, not the cleaned object
- ⚠ Boolean validation treats 'true'/'false' strings correctly but not '1'/'0' — use custom validator for numeric booleans if deployment uses 0/1
- ⚠ url() validator requires a fully qualified URL with protocol — 'localhost:3000' fails; use str() or custom validator for host:port values without protocol
- ⚠ cleanEnv() must be called before any other imports that use env variables for fail-fast behavior to work correctly
- ⚠ Default values override missing env vars silently — test that required variables without defaults actually fail when missing; envalid provides opt() for optional vs str() for required
- ⚠ TypeScript inference requires envalid 8.x — older versions need explicit type annotation; update for auto-typed cleanEnv return value
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for envalid.
Scores are editorial opinions as of 2026-03-06.