Node-config-env NPM

Config module

Simple module to load and query configuration files (.js, .json)

Installation

In your project folder run:

npm install --save node-config-env

Note: The module code uses few ES6 features, so at least 4.4.5 version of Node is required.

Usage

First you need to include the module and configure it.

const config = require('node-config-env').create('config/folder', 'environment');

Require the module and call create factory method that with two arguments:

path to the folder where the configuration files reside
name of the environment

By default, supported environment names are: dev, test, prod. You can supply custom environments by calling the factory function with additional parameter:

const config = require('node-config-env').create(__dirname + '/config', 'local', ['local', 'server']);

In this case, the config module is initialized to load config files based on local environment from a folder named config. The last parameter tells the config module what the supported environments are.

Configuration environments

In order to work as expected, the config module relies on configuration files to be stored in single directory (where they can be structured in sub-folders) and follow naming conventions based on supported environments.

Example of flat configuration file structure:

└─ project
	├─ config
    │   ├─ database.js      (default configuration file - required)
    │   ├─ database.dev.js  (extended configuration - optional)
    │   └─ database.prod.js (extended configuration - optional)
    └─ app.js

In app.js the config module is initialized with prod environment:

const config = require('node-config-env').create(__dirname + '/config', 'prod');

Let's look at configuration files' structure. In case the file extension is .js, the configuration is an object literal that is exposed in standard way for node modules utilizing module.exports.

(file: database.js) 
module.exports = {
    host: 'localhost',
    database: 'test',
    user: 'root',
    password: '',
};

(file: database.prod.js) 
module.exports = {
    host: '192.168.1.23',
    database: 'dbname',
    user: 'dbuser',
    password: '5up3r53cr3t',
};

Configuration can be stored in .json files as well. In that case, the file content is valid JSON:

(file: database.json) 
{
    "host": "localhost",
    "database": "test",
    "user": "root",
    "password": ""
}

If the base file has the .json extension, the extension files need to follow that convention too.

Configuration files can be named in any way but need to follow common patterns:

<basename>.js or <basename>.json for default configuration file - this is only required file and the name is used to query configuration object
<basename>.<env>.js or <basename>.<env>.json - this file is optional and if present it adds to/extend the base file

Configuration queries

The main purpose of the config module is to query configuration files.

config.get('<file>'); // loads whole configuration file
config.get('<file>.<path>'); // loads part of the configuration file based on path
config.get('<file>.<path>', 'default'); // a default value can be specified in case the path cannot be resolved

The <path> follows dotted convention to traverse configuration objects.

Let's query the database configuration for host:

let host = config.get('database.host'); // yep, it's that simple

Or user name, assuming there is a file users.js (or .json) with (json-encoded) array of users:

let name = config.get('users.0.credentials.name');

The configuration files can be stored in subfolders. Path to the file is then relative to the configuration folder that the module was initialized with.

let item = config.get('path/to/items.0');

Behavior

For queries, you start with the base file name and optionally follow with a path to traverse the cofiguration object. If there is a relevant extension file (based on environment), the default configuration is merged with the extended configuration and accessed in a transparent way. In case the extension file is missing, no error is thrown and the queries are resolved only on default configuration (loaded form base file). This can be confusing, so you'd better double check that all files are in place. For queries that cannot be resolved, an undefined value is returned (again, no error). You can use the config.has() method to check if the query is valid or check the returned value of the query for undefined.

Because the config module uses node's require function to load configuration files (that are cached by default), every update of configuration files therefore requires the application to be restarted.

Runtime configuration

The configuration folder and environment (as well as supported environments) can be changed on-the-fly.

config.setDir(__dirname + '/superconfig');    // throws Error if the folder does not exist
config.setEnv('test');    // throws Error if the environment is not supoorted
config.setEnv('default', ['testing', 'default']);   // setting new environment plus supported environments