exp-config

Loads configuration from JSON files from a <app_root>/config directory. The loaded configuration file can differ depending on the environment (determined by the NODE_ENV environment variable). It's also possible to override configuration values using a file named .env in <app_root> and by specifying them as environment variables.

Basic usage

npm install exp-config

Create a file named development.json in a folder named config in the application's root directory, such as:

{
  "someProp": "some value"
}

In your code require exp-config and retrieve the configuration value:

var config = require("exp-config");
var configuredValue = config.someProp;

You can also nest properties in the configuration files:

{
  "server": {
    "host": "google.com"
  }
}

var config = require("exp-config");
var configuredValue = config.server.host;

Booleans need special care:

var config = require("exp-config");
if (config.boolean("flags.someFlag")) {
  ...
}

If you just use config.flags.someFlag to prevent the string "false" (which is truthy) to cause problems.

Different configuration files for different environments

By default exp-config loads <app_root>/config/development.json. This behavior is typically used for local development and changed by specifying a different environment using the NODE_ENV environment variable, like this:

$ NODE_ENV=production node app

When starting an application in this way exp-config will instead load <app_root>/config/production.json. Likewise, it's common to have a separate configuration file for tests, and using NODE_ENV=test when running them.

Overriding configuration values

Individual values in the loaded configuration can be overridden by placing a file named .env in the application's root (<app_root>/.env). An example .env file can look like this:

someProp=some other value
server.host=example.com
flags.someFlag=true

It's also possible to override configuration by specifying them as environment variables when starting the application, like this:

$ someProp=value node app

To override nested properties with environment variables do like this:

$ env 'flags.someFlag=false' node .

Specifying other .env file

By default exp-config uses a file called .env in the root folder, you can override this by setting an environment variable named ENV_PATH to the new files path and name. NOTE: this is relative to the projects root folder.

$ ENV_PATH=relative/env/path/.envfile node /home/someuser/myapp/app.js

Precedence and values in tests

Values are loaded with the following precedence:

Environment variable
.env file
Configuration file

In other words, environment variables take precedence over .env files and configuration files.

NOTE, there is one exception: When NODE_ENV equals test (NODE_ENV=test) the .env file and environment variables are ignored. We want the test process to be as isolated and repeatable as possible, and are therefore minimizing the possibility of sticky human fingers messing with its configuration.

NOTE II, exception to the exception: If you want environment variables to be honored in the test environment, you can set the ALLOW_TEST_ENV_OVERRIDE environment variable. This is useful for overriding certain configurations when doing in-container testing. The .env file will still be ignored however.

Specifying the root folder

By default exp-config tries to locate the config folder and the (optional) .env file by using process.cwd(). This works great when starting the application from it's root folder. However, sometimes that's not possible. In such cases the root path can be specified by setting an environment variable named CONFIG_BASE_PATH, like this:

$ CONFIG_BASE_PATH=/home/someuser/myapp/ node /home/someuser/myapp/app.js

Usage pattern

An application using exp-config typically have a directory structure like this:

.
├── .env <-- Overrides for local development, not committed to source control
├── config <-- Configuration files committed to source control
|   ├── development.json <-- default file, used during local development
|   ├── production.json <-- used in production by setting NODE_ENV
|   └── test.json <-- used in tests by setting NODE_ENV
└── app.js <-- the app

henhan / exp-config