Convict

Convict expands on the standard pattern of configuring Node.js applications in a way that is more robust and accessible to collaborators who may have less interest in digging through code to inspect or modify settings. By introducing a configuration schema, Convict gives project collaborators more context on each setting and enables validation with early, descriptive failures when configuration goes wrong.

Maintained by Mozilla, Convict merges configuration from defaults, files, environment variables, and command-line arguments into a single validated object, making it a long-standing choice for Node.js services that need predictable, fail-fast configuration handling.

What You Get

• A schema-first API (convict({...})) for declaring config keys with docs, defaults, formats, env var and CLI arg bindings
• Automatic merging of defaults, JSON/JSON5/YAML/TOML config files, environment variables, and command-line arguments
• Built-in format validators (String, Number, Boolean, Array, port, *) plus support for custom formats via addFormat
• A .validate() method that produces a consolidated error report instead of failing on the first bad value
• Nested configuration structure support so related settings can be grouped hierarchically
• Companion packages (convict-format-with-validator, convict-format-with-moment) adding email/IP/URL/date formats

Common Use Cases

• Centralizing environment-specific configuration (dev/test/production) for a Node.js service in one validated schema
• Documenting configuration options for other engineers via the schema’s doc fields instead of a separate config wiki page
• Failing fast at process startup when required environment variables or config values are missing or malformed
• Layering configuration sources (defaults → file → env vars → CLI args) with a single deterministic precedence order

Under The Hood

Architecture: Convict’s core lives in a single ~780-line src/main.js module (packages/convict) built around a convict(schema) factory that walks the declared schema tree, wrapping each leaf key with metadata (doc, format, default, env, arg) and building a nested config object with .get(), .set(), .has(), and .validate() methods. Configuration sources are merged in a fixed precedence — schema defaults, then loaded files (via .loadFile()), then environment variables, then command-line arguments (parsed with yargs-parser) — with lodash.clonedeep used to avoid mutating the original schema defaults. The repo is a Lerna-Lite monorepo splitting the core (convict) from optional format packages (convict-format-with-validator, convict-format-with-moment), keeping the core dependency-light. Tech Stack: The core package has only two runtime dependencies (lodash.clonedeep, yargs-parser), keeping it lightweight; the monorepo’s devDependencies (Jest, ESLint, coveralls, json5, js-yaml, toml) support testing and multi-format file loading. It targets Node.js >=6, reflecting its long history as a Mozilla-maintained project since 2012. Code Quality: The test/ directory is extensive, with dedicated suites for schema parsing, format validation, file loading, nesting, CLI argument handling, and even a prototype_pollution.test.js guarding against a known class of config-injection vulnerability — a strong signal of security-conscious maintenance. npm test runs Jest with coverage reporting wired to Coveralls, and linting is enforced via a posttest hook. API Design: The schema-first API is declarative and self-documenting — each key’s doc, format, default, and env/arg bindings double as living documentation, and .validate({allowed: 'strict'}) returns a consolidated error report rather than throwing on the first bad value, which is friendlier for debugging misconfigured deployments than typical single-error validators.