convict
Schema-based configuration management for Node.js that validates configuration values against a defined schema. Merges configuration from multiple sources (default values, config files, environment variables, command-line arguments) with type coercion and validation. Created by Mozilla for managing complex multi-environment configurations.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Local configuration library. No secret masking built-in — sensitive values loaded from env vars are stored in plain memory objects. Avoid logging config objects that contain credentials.
⚡ Reliability
Best When
You need schema-validated configuration management for a Node.js service with multiple environments and configuration sources that must be validated at startup.
Avoid When
You're using TypeScript and want full type safety — use zod with dotenv or @t3-oss/env-nextjs for end-to-end typed configuration.
Use Cases
- • Define typed configuration schemas with defaults, environment variable bindings, and validation rules for agent services
- • Validate all required environment variables at startup and fail fast with descriptive errors for agent deployments
- • Merge configuration from multiple sources (JSON files, env vars, CLI args) with priority ordering for agent configuration
- • Generate configuration documentation from schema definitions for agent service configuration reference
- • Coerce environment variable strings to typed values (numbers, booleans, arrays) automatically in agent processes
Not For
- • Simple single-file configuration without validation — dotenv alone is sufficient for basic env var loading
- • TypeScript-first projects — convict's TypeScript support is bolted-on; use zod or @t3-oss/env-nextjs for type-safe config
- • Applications using cloud-native secret management — convict doesn't integrate natively with Vault, AWS Parameter Store, etc.
Interface
Authentication
Local configuration library — no authentication required.
Pricing
Apache 2.0 license. Mozilla-maintained open-source project.
Agent Metadata
Known Gotchas
- ⚠ convict v6 changed to ES module with breaking changes from v5 — JSON schema format and custom format registration API changed; check migration guide when upgrading
- ⚠ TypeScript type inference for config.get('nested.key') returns any — requires manual type casting; envalid or zod provide better TypeScript integration
- ⚠ validate({ allowed: 'strict' }) rejects unknown config keys — useful for detecting typos but breaks when adding new config without updating schema
- ⚠ Environment variable binding via env: 'MY_VAR' in schema only works for top-level env vars — nested dotted paths don't map to nested env vars automatically
- ⚠ convict does not watch config files for changes — config is loaded once at startup; dynamic config reload requires manual implementation
- ⚠ Sensitive values (passwords, API keys) are visible in get() output — implement a custom format or redact before logging; no built-in secret masking
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for convict.
Scores are editorial opinions as of 2026-03-06.