config vs dotenv vs dotenv-expand vs dotenv-flow
Environment Variable Management and Configuration Strategies in Node.js
Search packages..
configdotenvdotenv-expanddotenv-flowSimilar Packages:

Environment Variable Management and Configuration Strategies in Node.js

dotenv is the standard utility for loading environment variables from a .env file into process.env, enabling separation of secrets from code. config (node-config) provides a hierarchical configuration system that loads structured files (JSON, YAML, JS) based on the deployment environment, separate from environment variables. dotenv-expand extends dotenv by allowing variable substitution within .env files, reducing repetition. dotenv-flow enhances dotenv by automatically loading environment-specific files (like .env.development) based on NODE_ENV, simplifying multi-environment setups.

Npm Package Weekly Downloads Trend

3 Years

Github Stars Ranking

Stat Detail

Package
Downloads
Stars
Size
Issues
Publish
License
config06,427177 kB1021 days agoMIT
dotenv020,497103 kB63 months agoBSD-2-Clause
dotenv-expand01,05319 kB53 months agoBSD-2-Clause
dotenv-flow090260.3 kB83 years agoMIT

Environment Configuration Strategies: config vs dotenv vs dotenv-expand vs dotenv-flow

Managing settings across development, testing, and production is a core challenge in Node.js architecture. The packages config, dotenv, dotenv-expand, and dotenv-flow all address this problem but use different strategies. dotenv focuses on loading environment variables, config manages hierarchical application settings, while dotenv-expand and dotenv-flow extend the basic dotenv functionality. Let's compare how they handle loading, expansion, and environment switching.

📥 Loading Mechanisms: Process Env vs Config Objects

dotenv loads variables from a .env file directly into process.env.

  • It modifies the global process environment.
  • Best for simple key-value secrets.
// dotenv: Load .env into process.env
require('dotenv').config();
console.log(process.env.DB_HOST);

config loads structured files from a config/ directory into a configuration object.

  • It does not modify process.env by default.
  • Supports JSON, YAML, JS, and COFFEE files.
// config: Load from config/ directory
const config = require('config');
console.log(config.get('db.host'));

dotenv-expand modifies the result of dotenv before applying it.

  • It parses the .env file and expands variables in memory.
  • Still loads into process.env eventually.
// dotenv-expand: Expand then load
const dotenv = require('dotenv');
const dotenvExpand = require('dotenv-expand');
dotenvExpand.expand(dotenv.config());
console.log(process.env.DB_URL);

dotenv-flow loads multiple files based on environment into process.env.

  • It merges .env, .env.local, and environment-specific files.
  • Works like dotenv but with file hierarchy.
// dotenv-flow: Load hierarchy into process.env
require('dotenv-flow').config();
console.log(process.env.DB_HOST);

🔗 Variable Expansion: Static vs Dynamic Values

dotenv does not support variable expansion out of the box.

  • Values are treated as static strings.
  • Repeating values requires manual updates.
// dotenv: No expansion support
// .env file:
// HOST=localhost
// PORT=3000
// URL=localhost:3000 (This will be literal text)

config supports variable expansion within configuration files.

  • You can use custom variables or environment variables.
  • Defined in the configuration file structure.
// config: Expansion in config files
// config/default.js
module.exports = {
  url: '${HOST}:${PORT}'
};

dotenv-expand adds expansion syntax to .env files.

  • Uses ${VAR} or $VAR syntax.
  • Solves the repetition problem for dotenv.
// dotenv-expand: Expansion in .env
// .env file:
// HOST=localhost
// PORT=3000
// URL=${HOST}:${PORT} (This resolves correctly)

dotenv-flow relies on dotenv rules unless paired with expand.

  • By default, it does not expand variables.
  • Can be combined with dotenv-expand for full support.
// dotenv-flow: No expansion by default
// .env file:
// URL=${HOST}:${PORT} (Literal text without expand plugin)

🌍 Environment Hierarchies: Manual vs Automatic

dotenv requires manual file management for environments.

  • You must specify the path for each environment.
  • Common pattern: .env.development, .env.production.
// dotenv: Manual path selection
require('dotenv').config({ path: `.env.${process.env.NODE_ENV}` });

config has built-in hierarchical environment loading.

  • Automatically loads default.js then production.js.
  • Merges settings based on NODE_ENV.
// config: Auto hierarchy
// config/default.js (loaded always)
// config/production.js (loaded if NODE_ENV=production)
const config = require('config');

dotenv-expand does not handle environment files.

  • It only processes the file given to it.
  • Must be combined with logic to select files.
// dotenv-expand: No file hierarchy
// Requires manual path logic like dotenv above
const dotenv = require('dotenv');
dotenvExpand.expand(dotenv.config({ path: '.env.prod' }));

dotenv-flow automates environment file loading.

  • Loads .env, .env.local, .env.development, etc.
  • No need to write path logic manually.
// dotenv-flow: Auto hierarchy
// Loads .env + .env.development automatically
require('dotenv-flow').config();

🔑 Accessing Values: process.env vs Config Object

dotenv uses the global process.env object.

  • Access values like standard environment variables.
  • All values are strings by default.
// dotenv: Access via process.env
const port = process.env.PORT; // Returns string "3000"

config uses a dedicated configuration object.

  • Access values via config.get('key').
  • Supports nested objects and typed data.
// config: Access via config object
const port = config.get('server.port'); // Returns number 3000

dotenv-expand uses the global process.env object.

  • Same access pattern as standard dotenv.
  • Values remain strings after expansion.
// dotenv-expand: Access via process.env
const url = process.env.URL; // Returns string "localhost:3000"

dotenv-flow uses the global process.env object.

  • Same access pattern as standard dotenv.
  • Values remain strings regardless of file source.
// dotenv-flow: Access via process.env
const port = process.env.PORT; // Returns string "3000"

📊 Summary: Key Differences

Featuredotenvconfigdotenv-expanddotenv-flow
Primary Targetprocess.envConfig Objectprocess.envprocess.env
File Formats.envJS, JSON, YAML.env.env
Variable Expansion❌ No✅ Yes✅ Yes❌ No (unless paired)
Env Hierarchy❌ Manual✅ Automatic❌ Manual✅ Automatic
Data TypesStringsTyped (Num, Obj)StringsStrings

🤝 Similarities: Shared Ground

While these tools have different goals, they share common ground in managing application settings.

1. 🔒 Security Best Practices

  • All encourage keeping secrets out of source code.
  • None commit sensitive .env or config files to git by convention.
// All: .gitignore example
.env
.env.local
config/local.js

2. 🌐 NODE_ENV Reliance

  • All rely on NODE_ENV to determine behavior.
  • Production settings are triggered by this variable.
// All: Check environment
if (process.env.NODE_ENV === 'production') {
  // Load secure settings
}

3. 🛠️ Development Experience

  • All simplify local development setup.
  • Reduce boilerplate code for loading settings.
// All: One line setup
require('package-name').config();

💡 The Big Picture

dotenv is the foundational tool 🧱 — perfect for simple projects needing basic secret loading. It is the default choice for most Node.js apps.

config is the structured alternative 🗄️ — best for complex apps needing hierarchical, typed configuration separate from environment variables.

dotenv-expand is the enhancer 🔌 — use this when you need variable substitution within your .env files to reduce duplication.

dotenv-flow is the automator 🤖 — ideal when you want multiple environment files loaded automatically without custom path logic.

Final Thought: For most modern applications, a combination works best. Use dotenv-flow (with dotenv-expand) for environment variables and secrets, and reserve config for complex, structured application settings that require validation and hierarchy. Choose based on whether you need simple strings or structured data.

How to Choose: config vs dotenv vs dotenv-expand vs dotenv-flow

  • config:

    Choose config when you need a hierarchical configuration system that supports multiple file formats (JSON, YAML, JS) and merges settings based on deployment environment. It is ideal for complex applications where configuration logic exceeds simple key-value pairs and requires structured data validation. Use this when you want to keep configuration separate from system environment variables.

  • dotenv:

    Choose dotenv for the simplest scenario where you need to load a single .env file into process.env without extra features. It is the industry standard for basic secret management in local development and simple deployments. Use this when you do not need variable expansion or automatic environment-specific file loading.

  • dotenv-expand:

    Choose dotenv-expand if you need to reference other environment variables within your .env file to avoid repetition and maintain consistency. It works as a plugin to dotenv, enabling syntax like DB_URL=${HOST}:${PORT}. Use this when your configuration values depend on other variables defined in the same file.

  • dotenv-flow:

    Choose dotenv-flow if you want automatic loading of environment-specific files (like .env.development) based on NODE_ENV without writing custom logic. It simplifies managing different settings for local, test, and production environments seamlessly. Use this when you need a structured file hierarchy but prefer environment variables over structured configuration objects.

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 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 dotenv-expand

dotenv-expand is a package that extends the functionality of the popular dotenv library for managing environment variables in Node.js applications. It allows you to reference other environment variables within your .env files, enabling a more dynamic and flexible configuration setup. This is particularly useful when you need to create complex configurations that depend on multiple environment variables. By using dotenv-expand, you can easily manage and expand your environment variables without cluttering your codebase.

While dotenv-expand is a powerful tool for managing environment variables, there are several alternatives in the Node.js ecosystem that you might consider:

  • config is a 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 you to define defaults, environment-specific overrides, and even configuration hierarchies. If your application requires a more comprehensive configuration management solution beyond just environment variables, config is a great choice.
  • dotenv is the original library for loading environment variables from a .env file into process.env. It provides a straightforward way to manage environment variables but does not support variable expansion out of the box. If you only need basic environment variable management without the need for expansion, dotenv is a simple and effective solution.
  • dotenv-safe builds upon dotenv by adding a layer of safety to ensure that all required environment variables are defined. It allows you to specify a .env.example file that lists all the necessary variables, and it will throw an error if any of them are missing when loading the actual .env file. This is particularly useful for ensuring that your application has all the required configurations before it runs.

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

Similar Npm Packages to dotenv-flow

dotenv-flow is an npm package that extends the functionality of the popular dotenv library by allowing the use of multiple environment variable files. This is particularly useful for managing different configurations for various environments (like development, testing, and production) without cluttering a single .env file. With dotenv-flow, you can create environment-specific files such as .env, .env.local, .env.development, and so on, making it easier to organize and manage your environment variables.

While dotenv-flow is a powerful tool for managing environment variables, there are several alternatives in the ecosystem that also provide similar functionalities. Here are a few noteworthy options:

  • config is a configuration management library for Node.js applications that allows you to define configurations in JSON, YAML, or JavaScript files. It supports environment-specific configurations and provides a structured way to manage application settings. If you need a more comprehensive configuration management solution that goes beyond just environment variables, config is an excellent choice.

  • dotenv is the original library for loading environment variables from a .env file into process.env. It is simple and widely used in many Node.js applications. While it does not support multiple environment files out of the box, it is a solid choice for basic use cases where a single .env file suffices.

  • dotenv-expand is an extension of the dotenv library that allows for variable expansion within your .env files. This means you can reference other environment variables within your .env file, making it easier to manage related configurations. If you find yourself needing to reference other variables frequently, dotenv-expand can enhance your dotenv experience.

For a detailed comparison of these packages, check out the following link: Comparing config vs dotenv vs dotenv-expand vs dotenv-flow.

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/async, config/defer, config/parser, config/raw, 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.