smartive / node-application-config

package to provide application config with local config and environment support

node-application-config

Package to provide application config with local config and environment support. This package allows you to simply override config variables by defining local config files or environment variables.

Also nodeEnv, and isDebug are set based on NODE_ENV, which can be used in your code later on.

A bunch of badges

Features

Parse environment variables

If you want to parse other environmental variables into your application config, and you cannot (or you don't wanna) use process.env you can use the parsing feature. If you declare a config variable with the following pattern: ${ENV_VAR_NAME}, the config application will match it to the corresponding environment variable.

Example

export TEST_ENV_VAR=foobar

{
  "db": {
    "host": "${TEST_ENV_VAR}"
  }
}

In this case, config.db.host will be parsed to "foobar".

Require json file

If you need to require a json - yes only json, 'cause securty - file, you can do that with a special pattern. You need to use a relative filepath. If any error happens during the require process, the variable will have the value REQUIRE_ERROR and will have the error message attached.

The pattern for this feature is: !{filepath.json}.

Example

foobar.json

{
  "hello": "world" 
}

config.json

{
  "foobar": "!{./foobar.json}"
}

Results in:

{
  "foobar": {
    "hello": "world"
  }
}

Parse environment array variables

If you want to overwrite an array with a config variable (maybe you have a list of languages), you can overwrite the array with the following syntax:

ARRAY_ENV=str1|str2|str3

This feature is only necessary if you want to overwrite an array with environment variables, since you can use arrays in the config.json and the config.local.json files. If you want to overwrite a variable with a single element array or even an empty array, you can simply pass str1| for a single element array or | for an empty array.

Example

export app_config_arrayType=string1|string2|string3
export app_config_emptyArrayType=|
export app_config_singleElementArrayType=string1|

Results in:

{
  "arrayType": [
    "string1",
    "string2",
    "string3"
  ],
  "emptyArrayType": [],
  "singleElementArrayType": [
    "string1"
  ]
}

Usage

var appConfig = require('node-application-config'),
    config = appConfig(options);

Configuration

options is a hash with the following config variables:

startupPath

Base path for the application and for the config package to search for configurations

default: process.cwd()

configName

Name of the base configuration

default: config.json

localConfigName

Name of the local configuration (which overwrites the base config, but is not necessarily in the version control)

default: config.local.json

envConfigName

Name of the environment configuration (which overwrites the base config, but is not necessarily in the version control) ENV will be replaced with process.env.NODE_ENV!

default: config.ENV.json

environmentPrefix

Prefix for environment variables that overwrite the configurations

default: app_config_

environmentDelimiter

Which character is used for splitting the environment variables after the prefix is removed.

default: _

enableStateVariables

Enable the automatically set nodeEnv, isDebug, isStage and isProduction config variables, based on NODE_ENV. If no NODE_ENV is set, development is taken as fallback value.

default: true

Priorities

When merging config variables, the following priorities are taken into account:

1. Environment variable
2. Local config variable
3. Environment config file
4. Config variable

Example

config.json

{
  "db": {
    "user": "test",
    "pass": "testPass",
    "port": "10000"
  }
}

config.local.json

{
  "db": {
      "pass": "securePass",
      "host": "localhost"
  }
}

environment variable

app_config_db_port=1337

... results in:

var appConfig = require('node-application-config'),
    config = appConfig();

config.db.user == "test";
config.db.pass == "securePass";
config.db.host == "localhost";
config.db.port == 1337;

node-application-config's Issues

Possibility for default values when env vars are used

evaluate config variables

Implement a feature where a user of this package can evaluate a shell command.

e.g.

{
    "HOST_IP": "!{/sbin/ip route|awk '/default/ { print $3 }'}"
}

(this would set HOST_IP to the docker host ip)

redirect environment variables

Possible usecase, environment variable is already set, and you need to "rename" it in your application config.

e.g.

{
    "port": "${ENV_HOST_PORT}"
}

if ENV_HOST_PORT is set by a docker image or something like that.