JarCastingnodejs-read-config
Multi format configuration loader for Node.js. Features:
- Environmental variables replacement
- Configuration variables replacement
- Overriding configuration properties via environmental variables
- Variable default values
- Hierarchical configurations
- Supported format:
How to use
Environment variable replacement
/tmp/config.json:
{ env1: "%{ENV_VAR1}", env2: "%{ENV_VAR2|def}" }
index.js:
var readConfig = require('read-config'),
config = readConfig('/tmp/config.json');
console.log(config);
// $ ENV_VAR1=abc node index.js
// { env1: 'abc', env2: 'def' }
- It is possible to change
%to any other character. Just usereplaceEnvconfiguration option. - It is possible to use default values when environmental variable is not set.
Configuration overriding with system variables
/tmp/config.json:
{
rootProp: "rootProp",
objProp: {
x: 'X'
}
}
index.js:
var readConfig = require('read-config'),
config = readConfig('/tmp/config.json', { override: true });
console.log(config);
// $ ENV_VAR1=abc node index.js
// { rootProp: 'rootProp', objProp: { x: 'X'} }
// $ CONFIG_objProp_x=abc node index.js
// { rootProp: 'rootProp', objProp: { x: 'abc'} }
- It is possible to change
CONFIGto any other character. Just useoverrideconfiguration option. - It is possible to override existing value or create new one.
Configuration variable replacement
/tmp/config.json:
{
text1: "def",
text2: "abc-@{text1}-ghi"
number1: 1,
number2: "@{number1}",
boolean1: true,
boolean2: "@{boolean1}",
null1: null,
null2: "@{null1}",
obj1: {
x: 'X',
y: '@{./x}', // same as @{obj1.x}
z: '@{../text1}' // same as @{text1}
},
obj2: "@{obj1}"
}
index.js:
var readConfig = require('read-config'),
config = readConfig('/tmp/config.json');
console.log(config);
// $ node index.js
// {
// text1: "def",
// text2: "abc-def-ghi"
// number1: 1,
// number2: 1,
// boolean1: true,
// boolean2: true,
// null1: null,
// null2: null,
// obj1: {
// x: 'X',
// y: 'X',
// z: 'def'
// },
// obj2: {
// x: 'X',
// y: 'X',
// z: 'def'
// }
// }
- It is possible to use nested paths like
@{x.y.z} - It is possible to use relative paths like
@{./x}and@{../y} - It is possible to concatenate variables like
@{x}abc@{y}def@{ghi}
Configuration hierarchy
/tmp/config-1.json:
{
a: "a",
b: "b",
arr: [1, 2, 3]
}
/tmp/config-2.json:
{
__parent: "/tmp/config-1.json",
// same as: __parent: "./config-1.json",
b: "bb",
c: "aa",
arr: []
}
index.js:
var readConfig = require('read-config'),
config = readConfig('/tmp/config-2.json');
console.log(config);
// $ node index.js
// {
// a: "a"
// b: "bb",
// c: "aa",
// arr: []
// }
Hierarchy and basedir
/tmp/config-1.json:
{
a: "a",
b: "b",
arr: [1, 2, 3]
}
/home/xxx/config-2.json:
{
__parent: "config-1", // no directory & extension specified
b: "bb",
c: "aa",
arr: []
}
index.js:
var readConfig = require('read-config'),
config = readConfig('/tmp/config-2.json');
console.log(config);
// $ node index.js
// {
// a: "a"
// b: "bb",
// c: "aa",
// arr: []
// }
YAML config format
Using YAML representation lookout for special characters like: '%' and '@'.
/tmp/config.yml:
a: "@{LOCAL_VAR}"
b: "%{ENV_VAR}"
c: No quotes needed!
API
Functions
- readConfig(paths, [opts]) - Alias for
readConfig.sync(paths, [opts]). - readConfig.sync(paths, [opts]) - Loads configuration file synchronously.
- readConfig.async(paths, [opts], callback) - Loads configuration file asynchronously.
All json files are loaded using JSON5 library. It means you can add comments, and skip quotes in your config files - thank you json5;).
Parameters
- paths (String/Array) - path (or array of paths) to configuration file. If passed an array of paths than every configuration is resolved separately than merged hierarchically (like: [grand-parent-config, parent-config, child-config]).
- opts (Object, optional) - configuration loading options
- parentField - (Boolean/String, default: true) if specified enables configuration hierarchy. It's value is used to resolve parent configuration file. This field will be removed from the result. A string value overrides
__parentFieldproperty name. - optional - (String/Array, default: []) list of configuration paths that are optional. If any configuration path is not resolved and is not optional it's treated as empty file and no exception is raised.
- basedir - (String/Array, default: []) base directory (or directories) used for searching configuration files. Mind that
basedirhas lower priority than a configuration directory, process basedir, and absolute paths. - replaceEnv - (Boolean/String, default: false, constraint: A string value must be different than
replaceLocal) if specified enables environment variable replacement. Expected string value e.g.%that will be used to replace all occurrences of%{...}with environment variables. You can use default values like: %{a.b.c|some-default-value}. - replaceLocal - (Boolean/String, default: '@', constraint: A string value must be different than
replaceEnv) if specified enables configuration variable replacement. Expected string value e.g.@that will be used to replace all occurrences of@{...}with configuration variables. You can use default values like: @{a.b.c|some-default-value}. - override - (Boolean/String, default: false) If specified enables configuration overriding with environmental variables like
CONFIG_<propertyName>. - skipUnresolved - (Boolean, default: false)
trueblocks error throwing on unresolved variables.
- parentField - (Boolean/String, default: true) if specified enables configuration hierarchy. It's value is used to resolve parent configuration file. This field will be removed from the result. A string value overrides
Default opts values:
{
parentField: "__parent",
optional: [],
basedir: null,
replaceEnv: "%",
replaceLocal: "@",
skipUnresolved: false
}
Flow
Flow of the configuration loader:
- Merge all configs passed in path parameter with all of their parents (merging all hierarchy)
- Merge all results to one json object
- Override configuration with environment variables
- Resolve environment variables
- Resolve local variables
Gulp commands:
gulp checkstyle- runs jshint and jscsrc analysisgulp test- runs testsgulp test --file test/loader.js- runs single test file./test/loader.jsgulp- alias forgulp jshint testgulp test-cov- runs instrumented tests, generates reports to./build/testgulp test-cov --file test/loader.js- runs single instrumented test file./test/loader.jsgulp clean- removes./buildfoldergulp ci- alias forgulp clean checkstyle test-cov
NPM commands:
npm test- alias forgulp testnpm run ci- alias forgulp ci
