convict

library6.2.5jsnpmunverified

Convict is a featureful configuration management library for Node.js applications, providing schema-based validation, environment variable support, and command-line argument parsing. Version 6.2.5 is the latest stable release, with a slow release cadence (last release in 2021). Key differentiators include nested schema definitions, strict validation with error reporting, support for JSON5 comments, and the ability to extend with custom formats. Unlike dotenv or node-config, Convict enforces structure and types at load time, reducing runtime configuration errors.

devops

npm install convict

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CONVICT

convict

devopsjavascriptv6.2.5

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

convict

✓ import convict from 'convict'

✗ const convict = require('convict')

EJS module; use import or require as shown.

ConvictSchema

✓ import type { Schema as ConvictSchema } from 'convict'

TypeScript type import for defining schema objects.

Convict

✓ import convict from 'convict'; const config = convict(schema);

✗ const config = convict();

convict() must be called with a schema object (or empty {}).

Shows how to define a schema, load an environment-specific config file, and validate the configuration.

import convict from 'convict'; const config = convict({ env: { doc: 'The application environment.', format: ['production', 'development', 'test'], default: 'development', env: 'NODE_ENV', }, port: { doc: 'The port to bind.', format: 'port', default: 8080, env: 'PORT', arg: 'port', }, }); config.loadFile('./config/' + config.get('env') + '.json'); config.validate({ allowed: 'strict' }); export default config;

Debug

Known issues

deprecatedconvict.addFormat() is soft-deprecated; prefer using the formats option in convict constructor.

fix

Use convinct({ formatters: { ... } }) instead of convict.addFormat().

affects: >=6.0.0

gotchaValidation strict mode 'strict' rejects unknown schema keys. Use 'warn' to only log warnings.

fix

Set validate({ allowed: 'strict' }) only if you want to fail on unknown keys. For tolerant validation use 'warn'.

affects: >=4.0.0

gotchaConvict does not support single-hyphen command-line arguments; only double-hyphen (--arg) works.

fix

Use -- flag for all command-line arguments (e.g., --port 3000).

affects: >=0.0.0

deprecatedThe convict-format-with-validator package is deprecated; use built-in formats like 'ipaddress' instead.

fix

Remove convict-format-with-validator and rely on convict's built-in format validators.

affects: >=6.0.0

gotchaConvict's 'env' and 'arg' properties in schema do not automatically parse environment variables as JSON; they return strings.

fix

For JSON env vars, write a custom format that JSON.parse the value.

affects: >=0.0.0

Errors

Common errors & fixes

Error: Cannot find module 'convict-format-with-validator'

Missing optional dependency when using 'ipaddress' or other custom validators.

fix

Install the package: npm install convict-format-with-validator

TypeError: config.get is not a function

convict() was called without a schema, or the returned value was not stored correctly.

fix

Ensure you call convict(schema) and assign it to a variable: const config = convict({...});

Convict validation error: 'port' must be of type 'port'

Using format 'port' but the value cannot be parsed as a valid port number.

fix

Ensure the value is a number between 0 and 65535. For environment variables, check the value is set correctly.

Error: Unknown format: 'ipaddress'

Missing the custom format definition for 'ipaddress'.

fix

Use built-in format 'ipaddress' or add custom format via convict.addFormat() or formats option.

Upgrade

Version history

6.2.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/mozilla/node-convict#master ↗

packageconvict ↗

homepagehttps://github.com/mozilla/node-convict ↗