project-config
is a configuration tool, capable of handling configs for complex projects with many running environments. If you have node application with several different processes, sharing parts of configuration, this tool can be a good fit for you.
- Json-based configuration
- Loading of config files' names can be controlled via environment
- Config files for different environments can be stored in different directories
- Via usage of
append()
andprepend()
methods, application's configuration can be precisely tuned and even changed in runtime - Thanks to JSON5 config files can contain any comments needed to help undetstand meaning of the options
- Can produce js literal object (object created with literal notaion, also called hash and so many other names), that can be used as configuration for any libraries and existing projects
- Intented to be used at the start-up of application, so it is designed to be synchronous to simplify the code
With given file structure:
app.js
configs
defaults.json
app.development.json
app.production.json
Configs being:
// defaults.json
{
// database access parameters
"db": {
"provider": "mysql",
"host": "localhost",
"port": "3306",
"database": "app",
"user": "app",
"password": ""
},
// whether cache is enabled
"cache": true,
// logging level
"logLevel": "info"
}
// app.development.json
{
"db": {
"database": "app_dev"
},
"cache": false,
"logLevel": "debug"
}
// app.production.json
{
"db": {
"host": "...",
"password": "..."
},
"logLevel": "warning"
}
And code:
var Config = require('project-config');
Config.init();
var config = new Config('app');
config.prepend('defaults');
console.log(config.get());
Running node app --config-base-dir=configs --config-env=development
will result in:
{
"db": {
"provider": "mysql",
"host": "localhost",
"port": "3306",
"database": "appDev",
"user": "app",
"password": ""
},
"cache": false,
"logLevel": "debug"
}
And when in production and running node app --config-base-dir=configs --config-env=production
will result in:
{
"db": {
"provider": "mysql",
"host": "...",
"port": "3306",
"database": "app",
"user": "app",
"password": "..."
},
"cache": true,
"logLevel": "warning"
}
- Install it
npm install project-config
- Require and use it
var Config = require('project-config');
var config = new Config('/path/to/config/file');
console.log(config.get('resources:db:url'));
Create configuration management class. Constructor accepts optional argument data
with data to initialize config. New internal store will be created for it with main
name. It can be removed or replaced later.
All methods, that loads new data accept one parameter, that can be either a string or an object.
- A string, is treated as a path to config file to load. By default files is searched relative to current process's working directory (where node process was started) or by absolute path (if it was provided).
.json
suffix is not necessary. Note: as of 2.0.0, there are 3 files, that are tried for loading: file with suffix, set viaenv
variable (see below), file without suffix, file withdefaults
suffix. All files, that are found are loaded automatically. - Object is simply added as is.
Config.getBaseDir(dir), Config.setBaseDir(dir), Config.unsetBaseDir(dir), Config.getEnv(env), Config.setEnv(env), Config.unsetEnv(env)
These six methods affect how and which files are loaded. There are two options: base-dir
and env
.
base-dir
affects path, from where files are loaded. It can be used as a shortcut for all loaded config files by setting it to common prefix, i.e: Config.setBaseDir('./configs/'); config.add('cluster');
will result in loading of configs/cluster.json
file. Also it can be used to load all files from outside your git repository, which can be helpfull for production environments.
env
affects suffix added to config filename. I.e: Config.setEnv('test'); config.add('cluster');
will result in loading of cluster.test.json
file.
Reads env
value from from --config-env
command line argument, NODE_ENV
and CONFIG_ENV
environment variables and base-dir
value from --config-base-dir
command line argument and CONFIG_BASE_DIR
environment variable.
Adds all environment varibales to current configuration.
:
is used as namespace separator, i.e test:key=value
will result in {test:{key: value}}
. prefix
allows for only part of keys to be loaded into config. All loaded keys will be stripped of prefix (test:key=value loaded with
prefix=test will result in key=value in config). delimiter
allows to specify
alternative to :
to use, when loading env values.
Adds all command-line arguments to current configuration. :
is used as namespace separator. prefix
and delimiter
work the same as in addEnv()
.
Calls both addArgv()
and addEnv()
.
Add data to current config file. New values do not replace existing ones. data
param follows same rules as described in constructor. name
param is optional and gives a name for new store, so it can be removed later.
Same as add()
, but new values replace existing ones.
Add default storage, that always in front of all others. Only one default storage can exists, so more than one call to this method will overwrite previously added data.
Remove previously added store by name.
Get value of the key. :
is used for namespace separation. If no key provided, whole config will returned as object.
Set value for the key. :
is used for namespace separation. Set always overwrites existing values.
Create a deep copy of config object. There will be no links between old and new one.
Found a bug, have a feature proposal or want to add a pull request? All are welcome. Just go to issues and write it down.