Configure your Node.js Applications

      release notes

Introduction

nm-config organizes hierarchical configurations for your app deployments.

This repo was forked from node-config and add's additional functionality to allow for multilevel config directories. This is useful when using config in an npm package where that package will have it's own configuration. Your main application can then choose to override those configurations, if it also uses nm-config.

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 nm-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:

var config = require('nm-config');
//...
var dbConfig = config.get('Customer.dbConfig');
db.connect(dbConfig, ...);

if (config.has('optionalFeature.detail')) {
  var 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.

using config in submodules/npm packages:

If your npm package requires custom configuration, you can lay your configuration out in a hierarchical manner. Your folder structure could look like this:

/

• config
  • default.json
• node_modules
  • my_module
    • config
      • default.json
• index.js

{
  "key1": "value1",
  "key2": "value2"
}

{
  "key1": "perent",
  "key3": "value3"
}

var config = require('nm-config').withConfig('./config');
//...
var key1 = config.get('key1'); // key1 = parent
var key2 = config.get('key2'); // key2 = value2

var config = require('nm-config')
//...
var key3 = config.get('key3'); // key3 = key3
var key2 = config.get('key2'); // key2 = undefined

Articles

• 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

Contributors

tomkoufakis	lorenwest	markstos	elliotttf	leachiM2k	josx
enyo	arthanzel	eheikes	diversario	th507	Osterjour
nsabovic	ScionOfBytes	simon-scherzinger	axelhzf	benkroeger	IvanVergiliev
jfelege	jaylynch	jberrisch	kgoerlitz	nitzan-shaked	robertrossmann
roncli	superoven	wmertens	XadillaX	ncuillery	adityabansod
thetalecrafter

License

May be freely distributed under the MIT license.

Copyright (c) 2017 Tom Koufakis and other contributors