Config Attendant
Usage
JS
The only option is to pass Config Attendant the name of your app, and your default configuration.
var conf = appname //defaults go here. port: 2468 //defaults which are objects will be merged, not replaced views: engine: 'jade' ;
Config Attendant will return your configuration options merged with the defaults you specify. If you pass in a predefined defaults object, it will be mutated:
var conf = {};appname conf;
If Config Attendant finds any config files for your app, the returned config object will have
a configs
array containing their paths:
var appCfg = appname conf;appCfgconfigs0 // /etc/appnamercappCfgconfigs1 // /home/dominictarr/.config/appnameappCfgconfig // same as appCfg.configs[appCfg.configs.length - 1]
CLI
Installation
To use Config Attendant as a command line tool (nice for testing out configurations), install it globally via npm.
npm install -g config-attendant
Parameters passed as strings are interpreted as app names, flags and values are interpreted as configuration values.
$ config appname --prop 'value'
The only reserved flag is --config
which can be used to point to json config files to load as well.
$ config appname --prop 'value' --config config-attendant/test/defaults.json
Standards
Given your application name (appname
), Config Attendant will look in all the obvious places for configuration.
- command line arguments (parsed by minimist)
- environment variables prefixed with
${appname}_
- or use "__" to indicate nested properties
(e.g.
appname_foo__bar__baz
=>foo.bar.baz
)
- or use "__" to indicate nested properties
(e.g.
- if you passed an option
--config file
then from that file - a local
.${appname}rc
or the first found looking in./ ../ ../../ ../../../
etc. - a local
package.json
file or the first found looking in./ ../ ../../ ../../../
etc.- within the
package.json
the${appname}
value. - within the
package.json
,config.${appname}
.
- within the
$HOME/.${appname}rc
$HOME/.${appname}/config
$HOME/.config/${appname}
$HOME/.config/${appname}/config
/etc/${appname}rc
/etc/${appname}/config
- the defaults object you passed in.
All configuration sources that were found will be flattened into one object, so that sources earlier in this list override later ones.
Configuration File Formats
Configuration files (e.g. .appnamerc
) may be in either json or ini format. The example configurations below are equivalent:
ini
Formatted as ; You can include comments in `ini` format if you want. dependsOn=0.10.0 ; Config Attendant has built-in support for ini sections, see? [commands] www = ./commands/www console = ./commands/repl ; You can even do nested sections [generators.options] engine = ejs [generators.modules] new = generate-new engine = generate-backend
json
Formatted as // You can even comment your JSON, if you want "dependsOn": "0.10.0" "commands": "www": "./commands/www" "console": "./commands/repl" "generators": "options": "engine": "ejs" "modules": "new": "generate-new" "backend": "generate-backend"
Comments are stripped from JSON config via strip-json-comments.
Since ini, and env variables do not have a standard for types, your application needs be prepared for strings.
Advanced Usage
argv
Pass in your own You may pass in your own argv
object as the third argument to Config Attendant. This is in case you want to use your own command-line opts parser.
appname defaults customArgvObject;
Pass in your own parser
If you have a special need to use a non-standard parser,
you can do so by passing in the parser as the 4th argument.
(leave the 3rd as null to get the default argv object (what minimist
parses))
appname defaults null parser;
This may also be used to force a more strict format, such as strict, valid JSON only.
Note on Performance
Config Attendant is running fs.statSync
-- so make sure you don't use it in a hot code path (e.g. a request handler)
License
Multi-licensed under the two-clause BSD License, MIT License, or Apache License, version 2.0