config vs dotenv vs dotenv-safe vs env-cmd
Managing Environment Configuration in Node.js Applications
Search packages..
configdotenvdotenv-safeenv-cmdSimilar Packages:

Managing Environment Configuration in Node.js Applications

config, dotenv, dotenv-safe, and env-cmd are all widely used npm packages for managing environment-specific configuration in Node.js applications. They help separate sensitive or environment-dependent settings — such as API keys, database URLs, or feature flags — from application code. config uses hierarchical JSON or YAML files merged by environment name, providing a structured and immutable configuration object. dotenv loads variables from a .env file into process.env with no validation. dotenv-safe extends dotenv by requiring all keys defined in a .env.example file to be present, adding a safety net. env-cmd loads .env files via the command line before script execution, keeping configuration logic outside the application code itself.

Npm Package Weekly Downloads Trend

3 Years

Github Stars Ranking

Stat Detail

Package
Downloads
Stars
Size
Issues
Publish
License
config06,424207 kB14a month agoMIT
dotenv020,34893.3 kB10a month agoBSD-2-Clause
dotenv-safe077110.4 kB42 years agoMIT
env-cmd01,81655.2 kB257 months agoMIT

Managing Environment Configuration in Node.js: config vs dotenv vs dotenv-safe vs env-cmd

When building Node.js applications, managing environment-specific settings — like API keys, database URLs, or feature flags — is a foundational concern. The four packages under review (config, dotenv, dotenv-safe, and env-cmd) each tackle this problem differently, with distinct philosophies around source format, validation, runtime behavior, and deployment integration. Let’s examine how they work in practice and where each shines.

📁 Configuration Source: JSON Files vs .env Files vs CLI Overrides

config uses hierarchical JSON (or YAML/JS) files organized by environment name.

  • You create files like config/default.json, config/production.json, etc.
  • At runtime, it merges them based on NODE_ENV.
// config/default.json
{
  "db": {
    "host": "localhost",
    "port": 5432
  },
  "apiTimeout": 5000
}

// config/production.json
{
  "db": {
    "host": "prod-db.example.com"
  }
}

// In your app
const config = require('config');
console.log(config.get('db.host')); // 'prod-db.example.com' if NODE_ENV=production

dotenv, dotenv-safe, and env-cmd all rely on .env files (key=value format).

  • .env is loaded into process.env at startup.
  • They differ mainly in validation and loading mechanics.
# .env
DB_HOST=localhost
DB_PORT=5432
API_TIMEOUT=5000

// With dotenv
require('dotenv').config();
console.log(process.env.DB_HOST); // 'localhost'

env-cmd loads .env files via CLI, not inside your code.

  • It wraps your script command to inject environment variables before your app starts.
  • Your application code never calls env-cmd directly.
# package.json
{
  "scripts": {
    "start:dev": "env-cmd -f .env.development node server.js",
    "start:prod": "env-cmd -f .env.production node server.js"
  }
}

🔒 Validation: Optional vs Required vs Built-In

config provides schema-like validation through custom logic or external tools, but doesn’t enforce required keys out of the box.

  • You can check for missing values manually:
const config = require('config');
if (!config.has('requiredKey')) {
  throw new Error('Missing required configuration: requiredKey');
}

dotenv has no validation — it silently ignores missing or malformed entries.

  • If a key is missing from .env, process.env.MY_KEY will be undefined.

dotenv-safe enforces presence of all keys listed in a .env.example file.

  • It compares .env against .env.example and throws if any expected variable is missing.
# .env.example (defines required keys)
DB_HOST=
API_KEY=

// Throws if .env is missing DB_HOST or API_KEY
require('dotenv-safe').config();

env-cmd supports validation via --strict mode (as of v10+).

  • When enabled, it ensures every key in the .env file has a non-empty value.
env-cmd --strict -f .env node app.js
# Fails if any value in .env is empty

🧪 Runtime Behavior: Process Mutation vs Immutable Config

dotenv, dotenv-safe, and env-cmd all mutate process.env.

  • Once loaded, your app reads from process.env.MY_VAR.
  • This makes them simple but ties config access to global state.
// After dotenv loads
const port = process.env.PORT || 3000;

config provides an immutable, namespaced config object.

  • You never touch process.env directly for app settings.
  • This enables better testing (you can stub the config module) and avoids polluting the global environment.
const config = require('config');
const port = config.get('server.port');

💡 Note: config can read from process.env for overrides (e.g., CUSTOMER_DB_HOST overrides config.customer.dbHost), but its primary interface is the config object.

🛠️ Deployment and CI/CD Integration

env-cmd excels in script-driven environments like CI pipelines or Docker setups where you want to avoid bundling config logic into your app.

  • Since it works at the CLI level, your application remains “dumb” about config sources.
  • Ideal when you manage multiple .env files per environment and don’t want conditional logic in code.

dotenv and dotenv-safe are best when you ship .env files with your app (common in development or simple deployments).

  • Not recommended for production if secrets are checked into version control — but often used with CI systems that inject .env at build time.

config suits complex applications with layered configuration (e.g., SaaS platforms with tenant-specific overrides).

  • Supports local overrides (local.json), instance-specific configs, and runtime extensibility.
  • Works well in containerized environments where config is mounted as volume files.

🔄 Hot Reloading and Dynamic Updates

None of these libraries support live config reloading out of the box.

  • config offers a util/watchedFile utility for manual file watching, but it’s not automatic.
  • For dynamic config, consider pairing any of these with a dedicated solution like consul, etcd, or cloud-based parameter stores.

🧩 Real-World Scenarios

Scenario 1: Simple Web App with Dev/Prod Environments

You’re building a Next.js or Express app and need different DB URLs for dev and prod.

  • ✅ Best choice: dotenv (for simplicity) or dotenv-safe (if you want safety).
  • Why? Low overhead, familiar .env format, and sufficient for basic needs.
// .env.development
DB_URL=postgresql://localhost/myapp_dev

// .env.production
DB_URL=$PROD_DB_URL  // injected by CI

require('dotenv-safe').config({
  allowEmptyValues: true,
  example: '.env.example'
});

Scenario 2: Enterprise Application with Nested Config

Your app has deep configuration trees (e.g., integrations.stripe.apiVersion, logging.transports.console.level).

  • ✅ Best choice: config
  • Why? Native support for nested objects, merging, and programmatic access without string parsing.
// config/default.json
{
  "integrations": {
    "stripe": {
      "apiVersion": "2023-10-16",
      "webhookSecret": "..."
    }
  }
}

const config = require('config');
const stripeConfig = config.get('integrations.stripe');

Scenario 3: CI Pipeline with Strict Env Requirements

Your GitHub Actions workflow must fail fast if a required environment variable is missing.

  • ✅ Best choice: dotenv-safe or env-cmd --strict
  • Why? Both enforce completeness, reducing runtime surprises.
# GitHub Actions
- name: Run tests
  run: npx env-cmd --strict -f .env.test npm test

Scenario 4: Dockerized Microservice

You deploy containers and inject config via mounted .env files or Kubernetes secrets.

  • ✅ Best choice: env-cmd (if using file mounts) or dotenv (if copying .env into image)
  • Why? Decouples config loading from app logic; env-cmd keeps the app unaware of config mechanics.

📌 Summary Table

PackageConfig FormatValidationRuntime AccessBest For
configJSON/YAML/JSManual/customconfig.get('x')Complex apps, nested config, enterprise use
dotenv.envNoneprocess.env.XSimple apps, quick setup, dev environments
dotenv-safe.envRequired keys (via .env.example)process.env.XSafety-critical apps, CI/CD pipelines
env-cmd.env--strict modeprocess.env.XScript-driven deploys, Docker, no-code loading

💡 Final Recommendation

  • Need structure, nesting, and programmatic control? → Use config.
  • Want the simplest possible setup for local development? → Use dotenv.
  • Require guaranteed presence of all environment variables? → Use dotenv-safe or env-cmd --strict.
  • Prefer keeping config logic outside your application code? → Use env-cmd.

All four are actively maintained and safe for production use — the right choice depends entirely on your team’s workflow, deployment strategy, and tolerance for runtime risk.

How to Choose: config vs dotenv vs dotenv-safe vs env-cmd

  • config:

    Choose config if your application requires structured, hierarchical configuration with support for environment-specific overrides, nested objects, and programmatic access without mutating global state. It’s ideal for complex or enterprise-grade applications where configuration clarity, testability, and maintainability are critical.

  • dotenv:

    Choose dotenv if you need a lightweight, zero-config way to load environment variables from a .env file during development or simple deployments. It’s perfect for small to medium projects where validation isn’t a priority and you’re comfortable reading directly from process.env.

  • dotenv-safe:

    Choose dotenv-safe when you want the simplicity of .env files but require strict enforcement that all expected environment variables are defined—typically to prevent runtime errors in CI/CD pipelines or production. It’s a drop-in replacement for dotenv with added safety.

  • env-cmd:

    Choose env-cmd if you prefer managing environment configuration entirely outside your application code—such as in npm scripts, Dockerfiles, or CI workflows—and want to avoid bundling config-loading logic into your runtime. It’s especially useful when deploying to containerized or serverless environments.

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-safe

dotenv-safe is a package that extends the functionality of the popular dotenv library for managing environment variables in Node.js applications. It ensures that all required environment variables are defined in a .env file before the application starts, providing a safeguard against missing configuration. This is particularly useful in production environments where missing environment variables can lead to runtime errors. By using dotenv-safe, developers can define a .env.example file that lists all required variables, making it easier to manage and share environment configurations across different environments.

While dotenv-safe offers a robust solution for managing environment variables, there are several alternatives in the Node.js ecosystem:

  • config is a powerful configuration management library that allows developers to manage application settings across different environments. It supports JSON, YAML, and JavaScript files for configuration and can handle environment-specific configurations seamlessly. config is ideal for larger applications that require a more structured approach to configuration management, allowing for easy overrides and merging of settings based on the environment.

  • dotenv is the original library for loading environment variables from a .env file into process.env. It is simple to use and widely adopted in the Node.js community. While it does not provide the safety checks that dotenv-safe does, it is a lightweight solution for managing environment variables in smaller projects or when strict validation is not a priority.

  • dotenv-expand is an extension of the dotenv library that allows for variable expansion within the .env file. This means that you can reference other environment variables within your .env file, making it easier to manage complex configurations. While dotenv-expand does not provide the safety features of dotenv-safe, it is useful for projects that require more advanced variable management.

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

Similar Npm Packages to env-cmd

env-cmd is a utility for managing environment variables in Node.js applications. It allows developers to load environment variables from a specified file and make them available to their applications seamlessly. This is particularly useful for managing different configurations for development, testing, and production environments without hardcoding sensitive information into the codebase. With env-cmd, you can easily switch between different environment configurations by specifying the appropriate file.

While env-cmd is a powerful tool for handling environment variables, there are other alternatives in the ecosystem that also provide similar functionalities. Here are a couple of noteworthy alternatives:

  • cross-env is a popular package that allows you to set environment variables across different operating systems in a consistent manner. It is particularly useful for scripts defined in package.json, as it ensures that the environment variables are set correctly regardless of whether you're running the script on Windows, macOS, or Linux. cross-env is a great choice if you need to set environment variables directly in your npm scripts without worrying about platform compatibility.

  • dotenv is another widely used package for loading environment variables from a .env file into process.env. It is simple to use and integrates well with Node.js applications. By placing your environment variables in a .env file, you can easily manage configuration settings without exposing sensitive information in your code. dotenv is particularly useful for local development and testing, making it easy to set up and maintain environment-specific configurations.

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

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. Please share your feedback via our GitHub repository. For more details, please refer to our Terms & Privacy.