configr8
v1.0.0-rc.0
Published
.rc-style configuration files for node
Downloads
19
Maintainers
Readme
Configr8
It is useful to be able to provide a basic configuration with overrides based on system, runtime, user, environment, and other factors. .{name}rc
files provide a solid foundation for such configurations. Configr8 provides an API modeled loosely after rc and yargs, with a few helpful additions and potentially arbitrary quirks and opinions (discerning between these is left as an exercise for the reader.)
File Locations
Configr8 will look for and apply configuration files from the locations specified by the patterns
key in the settings you give it. It provides two named pattern sets which should meet most use cases - which you refer to by setting patterns
to their name, but you can also provide your own array of patterns.
The two named pattern sets are:
"application"
The "application"
patterns are appropriate for configuring an application. This is the default.
[
"${home}/.${name}rc",
"${cwd}/.${name}rc",
"${etc}/${name}rc",
]
"per-directory"
The "per-directory"
patterns are appropriate for configuring a tool that should act differently in different target directories.
[
"${parents}/.${name}rc",
"${home}/.${name}rc",
"${etc}/${name}rc"
]
The tokens in these patterns are substituted as follows:
${name}
- thename
string specified in settings. In all cases where a-
is found in the${name}
an additional-
will be inserted before any appendedrc
suffix. That is, files will be expected to be.hyphenated-app-name-rc
rather than.hyphenated-app-namerc
.${home}
- the current user's HOME directory or thehome
path specified in settings${cwd}
- the process' current working directory or thecwd
path specified in settings${etc}
- theetc
path specified in settings${parents}
- like${cwd}
except that it checks each parent of the current working directory back to the root of the file system.
Environment and Default Configuration Files
Additionally, these same file locations will be searched for environment-specific files, substituting ${name}-${environment}-
for ${name}
in the patterns above. The environment
searched for will be determined, in order of precedence, by the env
or environment
command line arguments (if parsed), the env
or environment
properties of any overrides passed in, or the ${name}_ENV
, ENV
, NODE_ENV
, or ENVIRONMENT
environment variables. If none of these is found, no environment-specific files will be loaded.
Similarly, these same filesystem locations will be searched for "defaults" files using ${name}-defaults-
instead of ${name}
.
Merging configuration
Configuration defaults are merged by first taking the values under the :defaults:
key in any standard configuration files, then configuration from any defaults configuration files, then the values under the :defaults:
key in any environment specific configuration files.
Environment specific configurations are merged with values under the [":env:"][environment]
key path from any defaults configuration files, then values under the [":env:"][environment]
key path from any standard configuration files, and finally the values in any environment specific configuration files.
Finally, the merged configuration defaults are overriden by the merged standard configuration, which is further overriden by the merged environment specific configuration.
The defaults object you pass in will be treated as the lowest priority defaults configuration file.
Configuration from environment varibles, overrides you pass in, and configuration from parsed command line arguments is then merged in order, giving command line arguments the highest precedence. These configuration sources do not provide a mechanism for specifying defaults or environment specific configuration because it is not needed.
Configuring Configr8
Configr8 exports a (synchronous) function that allows you to provide settings
describing how Configr8 should work. This will either be an app name
string or an object containing an name
property and other meta-configuration parameters. This function will return a configuration resolver function.
Settings
name
- Required. This is thename
that will be used to look up configurtion files and environment variables, etc.useArgv
- Default:false
. Indicates whether Configr8 should parseprocess.argv
for configuration. Default isfalse
because users will often pass in overrides from their own argv parser (or another source).useEnv
- Default:true
. Indicates whether Configr8 should parseprocess.env
for configuration.usePkg
- Default:true
. Indicates whether Configr8 should parsepackage.json
and get configuration from the key matchingname
.cwd
- Default:process.cwd()
. The path Configr8 should treat as the target or current working directory. It does not actually changeprocess.cwd()
.home
- Default: The user's home directory as determined byos-homedir
. The path Configr8 should treat as the user's home directory.etc
- Default:null
. The path Configr8 should treat as the system configuration directory.patterns
- Default:"application"
. The set of patterns to use to search for configuration files. (See File Locations above for details).async
- Default:false
. Indicates whether Configr8's configuration resolver function should return a Promise if no callback function is provided. Whenfalse
and no callback is provided the configuration resolver function will return the resolved configuration or anError
synchronously.
Installation
> npm install configr8 --save
Use
var configResolver = require('configr8')('my-app');
var defaultConfig = {
fiz: 'buzz',
blah: {
blarg: 2,
biz: 1
}
};
var config = configResolver(defaultConfig);
//...