node package manager



This module provides a simple asynchronous API for loading environment-specific config files and configuration data from other sources. This module utilizes the shortstop module to provide support for resolving values inside the configuration files based on user-provided "protocol handlers".

This module has extensive tests and is documented, stable and production-ready.

Table of Contents


npm install async-config --save


This module provides a simple API for loading environment-specific configuration files that is more flexible than alternatives. Its design was inspired by config and confit, but there are important differences. Unlike with the config module, this module does not use the exports of the module to maintain the loaded configuration. In addition, this module allows configuration files placed anywhere on disk to be loaded. Finally, this module provides an asynchronous API that allows configuration data to be loaded from remote sources and it avoids the use of synchronous I/O methods for reading files from disk. Compared to confit, this module is more flexible in how configuration files are named and located on disk.


The basic usage is shown below:

Given the following directory structure:

└── config
    ├── config.json
    ├── config-production.json
    └── config-development.json

Each configuration file should contain valid JSON data such as the following:

    "foo": "bar",
    "complex": {
        "hello": "world"

The following JavaScript code can be used to load the JSON configuration files and flatten them into a single configuration object:

require('async-config').load('config/config.json', function(err, config) {
    // The config is just a JavaScript object: 
    var foo =; 
    var hello = config.complex.hello;
    // Use the get() method to safely access nested properties: 
    var missing = config.get('complex.invalid.hello'); 

Load Order

When loading a configuration file, the following is the default order that configuration data is loaded:

  1. path/{name}.json
  2. path/{name}-{environment}.json
  3. path/{name}-local.json
  4. NODE_CONFIG='{...}' environment variable
  5. --NODE_CONFIG='{...}' command-line arguments

For example, given the following input of "config/config.json" and a value of production, the configuration data will be loaded and merged in the following order:

  1. path/config.json
  2. path/config-production.json
  3. path/config-local.json
  4. NODE_CONFIG environment variable
  5. --NODE_CONFIG='{...}' command-line arguments

The load order can be modified using any of the following approaches:

        sources: function(sources) {
            // Add defaults to the beginning: 
            // Add overrides to the end: 
            // You can also push an object instead of a path to a configuration file: 
                foo: 'bar'
            // You can also push a function that will asynchronously load additional config data: 
            sources.push(function(callback) {
                callback(null, {hello: 'world'});
        defaults: ['config/more-detaults.json'],
        overrides: ['config/more-overrides.json']
    function(err, config) {

Merging Configurations

A deep merge of objects is used to merge configuration objects. Properties in configuration objects loaded and merged later will overwrite properties of configuration objects loaded earlier. Only properties of complex objects that are not Array instances are merged.

Environment Variables


By default, the environment name will be based on the NODE_ENV environment variable. In addition, short environment names will be normalized such that prod becomes production and dev becomes development.


This environment variable allows you to override any configuration from the command line or shell environment. The NODE_CONFIG environment variable must be a JSON formatted string. Any configurations contained in this will override the configurations found and merged from the config files.


env NODE_CONFIG='{"foo":"bar"}' node server.js

Protocol Handlers

This module supports using protocols inside configuration files. For example, given the following JSON configuration file:

    "outputDir": "path:../build"

Protocol handlers can be registered as shown in the following sample code:

var configDir  = require('path').resolve(__dirname, 'config');
    require('path').join(configDir, 'config.json'),
        protocols: {
            path: function(path) {
                return require('path').resolve(configDir, path);
    function(err, config) {

Since the path protocol handler is used, the final value of the "outputDir" directory will be resolved to the full system path relative to the directory containing the configuration file. For example:

    "outputDir": "/development/my-app/build"

By default, the following protocol handlers are registered:


Loads another configuration given by a path relative to the current directory.

For example:

    "raptor-optimizer": "import:./raptor-optimizer.json"

Since the async-config module is used to load the imported configuration file, the imported configuration file will also support environment-specific configuration files. For example:

  1. ./raptor-optimizer.json
  2. ./raptor-optimizer-production.json


Resolves a relative path to an absolute path based on the directory containing the configuration file.


Resolves a value to the exports of an installed Node.js module.

For example:

    "main": "require:./app-production"

Command Line Arguments

By default, this module will merge configuration data from the --NODE_CONFIG='{...}' argument, but you can also easily merge in your own parsed command line arguments. For example, this module can be combined with the raptor-args module as shown in the following sample code:

var commandLineArgs = require('raptor-args').createParser({
        '--foo -f': 'boolean',
        '--bar -b': 'string'
        overrides: [commandLineArgs]
    function(err, config) {
        // Do something with the loaded config 

Therefore, if your app is invoked using node myapp.js --foo -b hello, then the final configuration would be:

    "foo": true,
    "bar": "hello",
    ... // Other properties from the config.json files 

App/Server Startup

It is common practice to load the configuration at startup and to delay listening on an HTTP port until the configuration is fully loaded. After the configuration has been loaded, the rest of the application should be able access the configuration synchronously. To support this pattern it is recommended to create a config.js module in your application as shown below:


var loadedConfig = null;
function configureApp(config, callback) {
    // Apply the configuration to the application... 
    // Make sure to invoke the callback when the application is fully configured 
// Initiate the loading of the config 
var configHandle = require('async-config').load(
        finalize: configureApp
    function(err, config) {
        if (err) {
            throw err;
        loadedConfig = config;
 * Synchronous API to return the loaded configuration:
exports.get = function() {
    if (!loadedConfig) {
        throw new Error('Configuration has not been fully loaded!');
    return loadedConfig;
 * Add a listener to be added for when the configuration is fully loaded.
 * If the configuration has already been fully loaded then the listener
 * will be invoked immediately.
exports.onConfigured = function(callback) {

If you are building a server app, your server.js might look like the following:

var express = require('express');
var config = require('./config');
// Asynchronously load environment-specific configuration data before starting the server 
config.onConfigured(function(err, config) {
    if (err) {
        throw err;
    var app = express();
    var port = config.port;
    // Configure the Express server app... 
    app.listen(port, function() {
        console.log('Listening on port', port);

For a working sample server application that utilizes this module, please see the source code for the raptor-samples/weather app.


load(path[, options, callback]) : AsyncConfigHandle

The load() method is used to initiate the asynchronous loading of a configuration. The following method signatures are supported:

load(path) : AsyncConfigHandle
load(path, options) : AsyncConfigHandle
load(path, options, callback) : AsyncConfigHandle

The path should be a file system path to a configuration file. If the path does not have an extension then the .json file extension is assumed. The input path will be used to build the search path.

The options argument supports the following properties:

  • defaults: An array of sources that will be prepended to the load order. Each source can be either a String file path, an async Function or an Object.
  • environment: The value of the environment variable (defaults to process.env.NODE_ENV or development).
  • excludes: An Array of sources to exclude. Possible values are the following:
    • "command-line" - ignore the --NODE_CONFIG command line argument
    • "env" - ignore the NODE_CONFIG environment variable
    • "env-file" - ignore path/{name}-{environment}.json
    • "local-file" - ignore path/{name}-local.json
  • finalize: An asynchronous Function with signature function (config, callback) that can be used to post-process the final configuration object and possibly return an entirely new configuration object.
  • helpersEnabled: If set to false then no helpers will be added to the configuration object (currently the get() method is the only helper added to the final configuration object). The default value is true.
  • overrides: An array of sources that will be appended to the load order. Each source can be either a String file path, an async Function or an Object.
  • protocols: An object where each name is the protocol name and the value is a resolver function (see the shortstop docs for more details).
  • sources: A function that can be used to modify the default load order.


The AsyncConfigHandle object returned by a call to the load() method supports the following properties:


Attaches a callback listener that will be invoked when the configuration has been fully loaded. If the configuration has already been fully loaded then the callback is invoked immediately. The signature of the callback function should be the following:

function callback(error, config)


  • Loaded config objects are not cached by this module.


  • Add support for YAML and other configuration file formats?



Pull requests, bug reports and feature requests welcome. To run tests:

npm install
npm test