config vs nconf vs dotenv vs rc
Node.js Configuration Management: Architectural Patterns and Trade-offs
Search packages..
confignconfdotenvrcSimilar Packages:

Node.js Configuration Management: Architectural Patterns and Trade-offs

config, dotenv, nconf, and rc are the four primary solutions for managing application settings in Node.js, but they solve different layers of the configuration problem. dotenv is a lightweight utility that simply loads environment variables from a .env file into process.env, acting as a bridge between the OS and your app. config provides a robust, hierarchical system that merges JSON, YAML, or JS files based on the NODE_ENV, enforcing a strict separation between code and config without relying solely on environment variables. nconf offers a flexible, hierarchical key-value store that can mix sources like files, memory, and environment variables, often used in older or highly dynamic setups. rc is a minimalistic parser designed specifically for command-line tools to read runtime configurations from flags, env vars, and standard config files (like .myapprc) simultaneously.

Npm Package Weekly Downloads Trend

3 Years

Github Stars Ranking

Stat Detail

Package
Downloads
Stars
Size
Issues
Publish
License
config1,560,2396,427159 kB152 months agoMIT
nconf1,066,9593,860162 kB1132 years agoMIT
dotenv020,54846.1 kB13 days agoBSD-2-Clause
rc01,022-378 years ago(BSD-2-Clause OR MIT OR Apache-2.0)

Node.js Configuration Management: Architectural Patterns and Trade-offs

Managing configuration is one of the first architectural decisions you make in a Node.js project. While it seems simple β€” just reading a few values β€” the approach you choose dictates how your app handles deployments, secrets, multi-environment setups, and CLI interactions. The four main players (config, dotenv, nconf, rc) are not interchangeable; they target different stages of the application lifecycle and different complexity levels.

Let's break down how they work, where they shine, and where they fall short.

πŸ—οΈ Core Philosophy: How They Load Data

The fundamental difference lies in where they look for data and how they merge it.

dotenv is the simplest. It does one thing: reads a .env file and dumps the key-value pairs into process.env. It doesn't understand hierarchy, types, or file merging. It assumes your app reads directly from process.env.

// dotenv: Simple injection into process.env
require('dotenv').config();

// Usage elsewhere
const dbHost = process.env.DB_HOST; 
// If DB_HOST isn't in .env or OS, this is undefined.

config ignores process.env by default (unless explicitly mapped). Instead, it looks into a config/ folder and merges files based on the NODE_ENV. It enforces a strict hierarchy: default.json is loaded first, then production.json overwrites it.

// config: Hierarchical file merging
// config/default.json: { "db": { "host": "localhost" } }
// config/production.json: { "db": { "host": "prod-db.example.com" } }

const config = require('config');
const dbHost = config.get('db.host'); 
// Automatically resolves to 'prod-db.example.com' if NODE_ENV=production

nconf creates a hierarchical store where you manually define the order of precedence (e.g., command line args > env vars > file). It acts as a key-value database for your settings.

// nconf: Manual hierarchy definition
const nconf = require('nconf');

nconf.argv().env().file({ file: 'config.json' });

const dbHost = nconf.get('db:host'); 
// Checks CLI args first, then ENV, then file.

rc is built for CLIs. It checks command-line arguments, environment variables, and a specific RC file (like .myapprc) in a predefined standard order. It returns a plain object.

// rc: Standard CLI config resolution
const rc = require('rc')('myapp', { port: 3000 });

// Usage: Reads from --port flag, MYAPP_PORT env, or .myapprc file
const port = rc.port;

🌳 Hierarchy and Environment Overrides

Real-world apps need different settings for development, staging, and production. How each package handles this defines its utility.

config excels here. It automatically detects NODE_ENV and loads corresponding files (development.json, production.json). You don't write if/else logic; the library handles the merge.

// config: Automatic environment switching
// No code changes needed. Just set NODE_ENV=staging
// Loads: default.json -> staging.json -> custom-environment-variables.json

const mailServer = config.get('mail.host');

dotenv has no built-in hierarchy. You must manage multiple files yourself (e.g., .env.development, .env.production) and load the correct one manually or via tooling like dotenv-cli.

// dotenv: Manual file selection
require('dotenv').config({ path: `.env.${process.env.NODE_ENV}` });

const mailServer = process.env.MAIL_HOST;
// You must ensure the correct file exists and is loaded.

nconf allows dynamic overrides at runtime. You can change a value in memory, and it persists for the app's life. This is powerful but can lead to "magic" behavior where config changes unexpectedly.

// nconf: Runtime overrides
nconf.set('feature:enabled', true); 
// Changes config in memory immediately

rc focuses on user-specific overrides. It looks for global config (/etc/myapprc), user config (~/.myapprc), and local config (.myapprc), allowing users to customize CLI behavior without changing code.

// rc: User-level hierarchy
// Merges defaults -> global -> user -> local -> env -> argv
const rc = require('rc')('myapp', { timeout: 5000 });

πŸ” Secrets and Security

Handling API keys and passwords is critical. The approach varies significantly.

dotenv is the most common for secrets because it keeps them out of code files. However, it relies entirely on the OS environment. If you accidentally commit .env, secrets are leaked.

// dotenv: Secret management
// .env file (gitignored)
DB_PASSWORD=supersecret

// App
require('dotenv').config();
const pass = process.env.DB_PASSWORD;

config discourages putting secrets in JSON files. Instead, it uses a special file custom-environment-variables.json to map env vars to config keys. This keeps your main config files safe to commit while pulling secrets from the environment.

// config: Secure mapping
// config/custom-environment-variables.json
// { "db": { "password": "DB_PASSWORD" } }

// App
const pass = config.get('db.password'); 
// Pulls from process.env.DB_PASSWORD automatically

nconf treats env vars as just another layer. You must ensure the env layer is higher priority than the file layer to prevent files from overriding secrets.

// nconf: Priority-based secrets
nconf.env(['DB_PASSWORD']).file('config.json');
// Env vars will override file values if priorities are set right

rc exposes secrets via environment variables prefixed with the app name. It's less explicit about security mapping compared to config.

// rc: Prefix-based secrets
// Set MYAPP_DB_PASSWORD in env
const rc = require('rc')('myapp');
const pass = rc.db_password;

πŸ› οΈ Developer Experience and Validation

How easy is it to catch errors when config is missing or malformed?

config throws clear errors if a requested key is missing (Error: Configuration property "db.host" is not defined). It also supports custom modules for validation logic, making it robust for large teams.

// config: Built-in validation
try {
  const port = config.get('server.port');
} catch (e) {
  // Throws explicit error if key is missing
  console.error(e.message);
}

dotenv offers no validation. If a variable is missing, you get undefined, which might crash your app later in a hard-to-debug place. You must add your own checks (e.g., using zod or manual if statements).

// dotenv: No validation
const port = process.env.PORT;
if (!port) throw new Error('PORT is required'); // Manual check needed

nconf returns null or undefined for missing keys. It provides a .required() method in some versions, but it's less standardized than config's approach.

// nconf: Basic checks
const port = nconf.get('port');
if (!port) { /* Handle missing */ }

rc returns defaults if nothing is found. It's designed to be permissive, assuming CLI tools should run with sensible defaults even if config is missing.

// rc: Defaults focused
const rc = require('rc')('myapp', { port: 3000 });
// If no config found, port is 3000. No error thrown.

πŸ“Š Summary: Key Differences

Featureconfigdotenvnconfrc
Primary UseComplex App ConfigSimple Env InjectionLegacy/Dynamic StoresCLI Tools
HierarchyAutomatic (File-based)None (Manual)Manual (Chainable)Standard (RC spec)
Env OverridesExplicit MappingDirect InjectionLayer PriorityPrefix Matching
ValidationStrong (Throws errors)NoneWeakNone (Defaults)
File FormatsJSON, JS, YAML, TOMLKey-Value (.env)JSON, IniJSON, Ini, YAML

πŸ’‘ The Big Picture

dotenv is the utility belt 🧰. It's small, everywhere, and solves the "how do I get .env into my app" problem. Use it for simple apps, scripts, or alongside other tools to inject secrets. It is not a full configuration system.

config is the enterprise vault 🏦. It provides structure, safety, and scalability. If your team grows, or if you have complex nested settings that change per environment, config pays for itself in reduced bugs and clearer architecture. It enforces discipline.

nconf is the legacy Swiss Army Knife πŸ”ͺ. It can do almost anything but requires more setup and care. Unless you are maintaining an older system that depends on it, modern alternatives like config usually offer a better developer experience.

rc is the CLI specialist πŸŽ›οΈ. If you are building a tool that developers install globally and configure via flags and dotfiles, rc is the standard. Don't use it for a standard web server backend.

Final Thought: For most modern Node.js backends, the winning combination is config for application structure + dotenv (or platform env vars) for secret injection. This gives you the hierarchy and validation of config while keeping secrets out of your files.

How to Choose: config vs nconf vs dotenv vs rc

  • config:

    Choose config for large-scale enterprise applications where configuration complexity grows over time. It is ideal when you need strict hierarchy (e.g., default.json overridden by production.json), type safety via custom modules, and the ability to change configs without redeploying code. Avoid it if you strictly adhere to the '12-Factor App' methodology that demands all config come exclusively from environment variables.

  • nconf:

    Choose nconf only if you are maintaining a legacy codebase that already relies on its specific hierarchical store pattern or if you need a very specific mix of asynchronous configuration sources. For new projects, avoid nconf in favor of config or dotenv due to its slower update cadence and more complex API surface for modern use cases.

  • dotenv:

    Choose dotenv for simple projects, local development setups, or serverless functions where you just need to inject secrets into process.env. It is the standard choice for bootstrapping apps quickly and works well with platforms like Vercel or Docker that manage env vars externally. Do not use it as your sole configuration strategy for complex apps requiring nested settings or runtime hierarchy merging.

  • rc:

    Choose rc if you are building a Command Line Interface (CLI) tool where users need to override settings via command-line flags, environment variables, and local config files simultaneously. It is the industry standard for developer tools (like linters or bundlers) but is generally unsuitable for standard web server applications where configuration is static at startup.

Similar Npm Packages to config

config is a popular npm package used for managing configuration settings in Node.js applications. It allows developers to define configuration files for different environments (development, production, etc.) and provides a simple way to access these settings throughout the application. The config package is particularly useful for applications that require a structured approach to configuration management, enabling developers to keep their code clean and organized.

While config is a robust solution, there are several alternatives available that cater to different needs and preferences:

  • convict is a configuration management library for Node.js that allows you to define a schema for your configuration. It provides validation, default values, and support for environment variables. convict is particularly useful for applications that require strict validation of configuration settings and want to ensure that all necessary parameters are provided. Its schema-based approach helps maintain consistency and clarity in configuration management.

  • dotenv is a simple and widely-used library that loads environment variables from a .env file into process.env. It is particularly useful for managing sensitive information like API keys and database credentials. While dotenv is not a full-fledged configuration management solution, it is often used in conjunction with other libraries to provide a straightforward way to manage environment-specific settings. If your application primarily relies on environment variables, dotenv is a great choice.

  • nconf is another configuration management library for Node.js that supports multiple sources of configuration, including command-line arguments, environment variables, and configuration files. It provides a flexible way to manage settings and allows for hierarchical configuration, making it easy to override values based on different contexts. nconf is suitable for applications that require a more dynamic approach to configuration management, allowing for easy adjustments based on various input sources.

To see how these packages compare, check out the comparison: Comparing config vs convict vs dotenv vs nconf.

Similar Npm Packages to nconf

nconf is a configuration management library for Node.js applications. It allows developers to manage application settings and configuration options in a flexible and hierarchical manner. With nconf, you can easily load configuration from various sources such as JSON files, environment variables, command-line arguments, and more. This versatility makes it a popular choice for applications that require a robust configuration management solution.

While nconf is a powerful tool, there are several alternatives available that also provide configuration management capabilities. Here are a few noteworthy options:

  • config is a popular configuration management library for Node.js applications that allows you to define application settings in a structured way. It supports multiple configuration files for different environments (development, production, etc.) and allows for easy overriding of settings. With its straightforward API and support for JSON and JavaScript configuration files, config is a great choice for applications that need a clear and organized way to manage settings across different environments.

  • convict is another configuration management library that focuses on schema validation. It allows you to define a schema for your configuration, ensuring that the settings adhere to specific types and constraints. This can help catch errors early in the development process. convict also supports loading configuration from various sources, including environment variables and JSON files, making it a flexible option for applications that require strict validation of their configuration settings.

  • dotenv is a simple and lightweight library that loads environment variables from a .env file into process.env. It is commonly used in Node.js applications to manage sensitive information like API keys and database credentials. While dotenv is not as feature-rich as nconf, config, or convict, it is an excellent choice for applications that need a straightforward way to manage environment variables without the overhead of a more complex configuration management solution.

To see how nconf compares with config, convict, and dotenv, check out the comparison: Comparing config vs convict vs dotenv vs nconf.

Similar Npm Packages to dotenv

dotenv is a popular npm package that allows developers to load environment variables from a .env file into process.env in Node.js applications. This is particularly useful for managing configuration settings, such as API keys and database connection strings, without hardcoding them into the source code. By using dotenv, developers can keep sensitive information secure and maintain different configurations for development, testing, and production environments.

While dotenv is widely used, there are several alternatives that offer similar functionality with additional features. Here are a few noteworthy options:

  • config is a powerful configuration management library for Node.js applications. It allows developers to define configuration settings in multiple formats (JSON, YAML, etc.) and supports environment-specific configurations. With config, you can easily manage complex configuration scenarios, making it a great choice for larger applications that require more than just environment variable management.

  • dotenv-safe is an extension of dotenv that adds a layer of safety by ensuring that all required environment variables are defined in the .env file. It allows you to specify a .env.example file that lists all the necessary variables, and if any are missing from the actual .env file, the application will throw an error. This feature helps prevent runtime errors due to missing environment variables, making it a good choice for teams and projects where configuration consistency is critical.

  • env-cmd is another alternative that allows you to load environment variables from a file when running your Node.js applications. It supports multiple environment files and can be used to specify which file to load based on the environment. This flexibility makes env-cmd a suitable option for projects that require different configurations for various environments without modifying the codebase.

To see how dotenv compares with config, dotenv-safe, and env-cmd, check out the comparison: Comparing config vs dotenv vs dotenv-safe vs env-cmd.

Similar Npm Packages to rc

rc is a configuration management library for Node.js applications. It allows developers to easily manage application settings and configurations by loading them from various sources such as environment variables, configuration files, and command-line arguments. This flexibility makes rc a popular choice for applications that require a robust and dynamic configuration management solution.

While rc provides a solid approach to configuration management, there are several alternatives in the Node.js ecosystem that also serve similar purposes. Here are a few notable alternatives:

  • config is a powerful configuration management library that allows you to manage application settings in a structured way. It supports multiple configuration files for different environments (development, production, etc.) and allows for easy overrides using environment variables. config is particularly useful for larger applications that require a well-organized configuration structure, making it easier to manage settings across different environments.

  • dotenv is a simple yet effective library for loading environment variables from a .env file into process.env. This approach is particularly useful for managing sensitive information such as API keys and database credentials without hardcoding them into your application. dotenv is lightweight and straightforward, making it a great choice for smaller projects or applications that primarily rely on environment variables for configuration.

  • nconf is another flexible configuration management library that supports multiple sources for configuration data, including environment variables, command-line arguments, and configuration files. It allows for hierarchical configuration, enabling you to set defaults and override them as needed. nconf is ideal for applications that require a more complex configuration setup, as it provides a comprehensive API for managing settings from various sources.

To see how rc compares with config, dotenv, and nconf, check out the comparison: Comparing config vs dotenv vs nconf vs rc.

README for config

Configure your Node.js Applications

npm package Downloads Issues

Release Notes

Introduction

Node-config organizes hierarchical configurations for your app deployments.

It lets you define a set of default parameters, and extend them for different deployment environments (development, qa, staging, production, etc.).

Configurations are stored in configuration files within your application, and can be overridden and extended by environment variables, command line parameters, or external sources.

This gives your application a consistent configuration interface shared among a growing list of npm modules also using node-config.

Project Guidelines

  • Simple - Get started fast
  • Powerful - For multi-node enterprise deployment
  • Flexible - Supporting multiple config file formats
  • Lightweight - Small file and memory footprint
  • Predictable - Well tested foundation for module and app developers

Quick Start

The following examples are in JSON format, but configurations can be in other file formats.

Install in your app directory, and edit the default config file.

$ npm install config
$ mkdir config
$ vi config/default.json

{
  // Customer module configs
  "Customer": {
    "dbConfig": {
      "host": "localhost",
      "port": 5984,
      "dbName": "customers"
    },
    "credit": {
      "initialLimit": 100,
      // Set low for development
      "initialDays": 1
    }
  }
}

Edit config overrides for production deployment:

 $ vi config/production.json

{
  "Customer": {
    "dbConfig": {
      "host": "prod-db-server"
    },
    "credit": {
      "initialDays": 30
    }
  }
}

Use configs in your code:

const config = require('config');
//...
const dbConfig = config.get('Customer.dbConfig');
db.connect(dbConfig, ...);

if (config.has('optionalFeature.detail')) {
  const detail = config.get('optionalFeature.detail');
  //...
}

config.get() will throw an exception for undefined keys to help catch typos and missing values. Use config.has() to test if a configuration value is defined.

Start your app server:

$ export NODE_ENV=production
$ node my-app.js

Running in this configuration, the port and dbName elements of dbConfig will come from the default.json file, and the host element will come from the production.json override file.

TypeScript

Type declarations are published under types/ and resolved via typesVersions. Subpath typings are included for config/parser, 'config/util/defer', and config/lib/util in addition to the main config entrypoint.

Articles

Further Information

If you still don't see what you are looking for, here are some more resources to check:

Contributors

lorenwestjdmarshallmarkstosiΒ­Moseselliotttfmdkitzman
jfelegeleachiΒ­M2kjosxenyoleosuncinarthanzel
leonardovillelajeremy-daley-krsimon-scherzingerBadgerΒ­BadgerΒ­BadgerΒ­Badgernsaboviccunneen
Osterjourth507tiny-rac00neheikesfgheorgheroncli
superovenairdrummingfoolwmertensXadillaΒ­Xinsidedsbert

License

May be freely distributed under the MIT license.

Copyright (c) 2010-2026 Loren West and other contributors

npm-compare.com is an independent website designed to help developers choose the most suitable npm packages. We are not affiliated with npm, Inc, the official website for the npm registry. Note that npm is a registered trademark of npm, Inc. For more details, please refer to our Terms & Privacy.