node-multiconfig

A recursive, hierarchical, multi-file, environment based configuration loader. It supports JSON, YAML, INI and CSON.

This module loads multiple .json files recursivly. It support different configurations for different environments (using the NODE_ENV environment variable). Inside configuration files you can specify environment variable placeholders using a prefix. All configurations for the given environment will be loaded into an object.

Installation

Install the module:

npm install multiconfig --save

Usage

In order to use this module, configuration files must be structured in a certain way. A config directory must be present in the root directory of your project. The config directory should have a default directory, in which default configurations are stored.

mkdir -p config/default

In your application configurations are accessible as an object, using the same pattern as the directory structure. By default, directory and file names are converted to camel case (this can be disabled).

Each directory can contain a file named index (which can be any of the support extensions, for example index.yaml). All the values of this file be a property of the directory name. (see example)

Optionally, for each environment (e.g. development, staging or production) another directory is created. In this directory you can create configurations that will override default configurations. The supportedd file types can be mixed. The environment is specified with the NODE_ENV environment variable.

mkdir config/production

Usage

var multiconfig = require('multiconfig');

var config = multiconfig.load();

// Do whatever you want with the 'config' object, 
// 'config' is just a regular Javascript object.

Optionally you can pass an options object as the first argument.

var options = {
    directory: '/path/to/config/directory', //specify the config directory (can be relative or absolute)
    env: 'staging', // Specify the environment
    prefix: '$ENV_VAR',
    pathCase: false // Don't convert directorie/file names to camelCase.
    configVariation: 1 // Use configs suffixed with "-1", "-2", etc. 
};

var config = multiconfig.load(options);

The default prefix is $ENV. It uses : as a separator. An example value in a configuration file: $ENV:YOUR_ENVIRONMENT_VAR_HERE. The value will be replaced by the actual value of the environment variable, if it exists. Check the example below.

The config variation to use can also be set using NODE_CONFIG_VARIATION environemnt variable. The config directory can also be specified using NODE_CONFIG_DIRECTORY an environment variable. Environment variables will have priority over inline configuration.

Example

This example uses JSON and YAML. other formats will work in the same way, just a different syntax. Assume we have an environment variable TEST_DATA with the value awesome. We have the following configuration files (note the paths):

./config/default/index.yaml

applicationName: multiconfig

./config/default/database/mongo.json

{
  "host": "127.0.0.1",
}

./config/default/compilers/java.json

{
  "version": "7",
  "name": "Java"
}

./config/production/compilers/java.json

{
  "version": "6",
  "debug": false  
}

./config/production/database/redis-config.json

{
  "database": "$ENV:TEST_DATA",
  "host": "10.0.0.1",
  "port": 9920
}

If an application is run without any environment specified, this will be the output of the configuration loader:

{
  "applicationName": "multiconfig",
  "compilers": {
    "java": {
      "version": "7",
      "name": "Java"
    }
  },
  "database": {
    "mongo": {
      "host": "127.0.0.1"
    }
  }
}

Note the camel case conversion of the redis-config file. By default every directory or filename will be converted to camel case.

If we run the application with NODE_ENV=production the output will be the following:

{
  "applicationName": "multiconfig",
  "compilers": {
    "java": {
      "version": "6",
      "name": "Java",
      "debug": false
    }
  },
  "database": {
    "mongo": {
      "host": "127.0.0.1"
    },
    "redisConfig": {
      "database": "awesome",
      "host": "10.0.0.1",
      "port": 9920
    }
  }
}