Configure your Node.js Applications

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

• Configuration Files
  • Special features for JavaScript configuration files
• Common Usage
• Environment Variables
• Reserved Words
• Command Line Overrides
• Multiple Node Instances
• Sub-Module Configuration
• Configuring from a DB / External Source
• Securing Production Config Files
• External Configuration Management Tools
• Examining Configuration Sources
• Using Config Utilities
• Upgrading from Config 0.x
• Webpack usage

Further Information

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

• The wiki may have more pages which are not directly linked from here.
• Review questions tagged with node-config on StackExchange. These are monitored by node-config contributors.
• Search the issue tracker. Hundreds of issues have already been discussed and resolved there.

Contributors

lorenwest	jdmarshall	markstos	i­Moses	elliotttf	mdkitzman
jfelege	leachi­M2k	josx	enyo	leosuncin	arthanzel
leonardovillela	jeremy-daley-kr	simon-scherzinger	Badger­Badger­Badger­Badger	nsabovic	cunneen
Osterjour	th507	tiny-rac00n	eheikes	fgheorghe	roncli
superoven	airdrummingfool	wmertens	Xadilla­X	inside	dsbert

License

May be freely distributed under the MIT license.

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