nixconfig
nixconfig is a configuration loader. It loads configuration from a set of well defined, traditional, paths. On non-win32 platforms the paths are:
/etc/
/etc/appname/
~/
~/.appname/
~/.config/appname
~/Application Support/Preferences/appname
(only on the Darwin platform)
On win32 platforms, the paths are:
~/AppData/Local/appname
Where appname
is the name within your application's
package.json
file.
On all platforms, it is possible to append a path by setting a
nixconfig_config_home
environment variable, e.g.
nixconfig_config_home=/tmp/testing node app.js
.
Example
const nixconfig = console // "bar" for {foo: 'bar'}console // "baz" for {foo: {bar: 'baz'}}
Config Loading
When an instance of nixconfig is created, it will iterate the list of paths
noted in the introduction in order from top to bottom. Within each
path it will run a set of configured loaders to load the files
within that path. For example, for an application named "foobar" the JSON loader
will attempt to load /etc/foobar.json
and /etc/foobar/foobar.json
and so on.
The values within /etc/foobar/foobar.json
will overwrite the same values
loaded from /etc/foobar.json
.
Important: this depends on your package.json
containing a name
property.
Loaders
nixconfig ships with three loader types:
- JavaScript
- JSON
- Environment
A loader is merely a function that returns a standard JavaScript object. Loaders are named by the extension they match or an artibtrary name if they do not process files. Thus, the default set of loaders is defined:
const loaders = '.js': require '.json': require {}
Notice that loaders which do not process files are prefixed with a ~
.
Loaders are processed in the order they are defined. Thus, without adding any other loaders, the default processing order for nixconfig is to load JavaScript files first, JSON second, and environment variables last.
It is possible to add custom loaders:
const nixconfig = loaders: ext: '.yaml' { // the full path to the file to load is supplied, e.g. // `file = '/etc/foobar.yaml'` } ext: '~notAFile' { // no parameter is passed }
Custom loaders will be appended to the standard set of loaders. All file loaders are processed prior to all non-file loaders.
Environment Loader
The environment loader looks for environment variables prefixed with either
nixconfig_
or the value of nixconfigPrefix
with the application's
package.json
. Thus, the environment variable nixconfig_foo=bar
would
result in console.log( nixconfig.get('foo') ) // 'bar'
.
The environment loader also supports setting deeply nested variables. To do so,
simply separate the object path properties with __
. For example,
nixconfig_foo__bar=foobar
would result in
console.log( nixconfig.get('foo.bar') ) // 'foobar'
.
API
The full API is documented in the API document.
Configuration
For the environment loader, you must set nixconfigPrefix
in your package.json
.
For example:
Otherwise the prefix will be nixconfig_
.
For general configuration, an object may be supplied to the exported factory function:
delim: '.' // String path delimeter for the `get` and `set` methods. logger: {} // A log4j API compliant logger like https://npm.im/pino (null logger by default). loaders: // An array of loader objects: `{ext: '.foo', method: (file) => {}}`. initialConfig: {} // Defaults to use if no configuration files are found., parentName: '' // Defaults to `undefined`. Name of the app. If set, so must be `parentPath`. parentPath: '' // Defaults to `undefined`. Absolute path to application root dir.
The loaders
property may also be an object wherein the keys are the extensions
and the values are the associated methods.
When parentName
and parentPath
are set nixconfig will use these values
to load the application's package.json
and the configuration files. For
example, given {parentName: 'not-foo', parentPath: '/tmp/foo'}
then nixconfig
will:
- Load the
/tmp/foo/package.json
file and update the loaded object'sname
property to be'not-foo'
. - Look for configuration files like
not-foo.json
andnot-foo.js
.