https://github.com/krakenjs/confit
Environment-aware configuration.
https://github.com/krakenjs/confit
Last synced: 3 months ago
JSON representation
Environment-aware configuration.
- Host: GitHub
- URL: https://github.com/krakenjs/confit
- Owner: krakenjs
- License: other
- Created: 2014-03-11T20:20:08.000Z (over 11 years ago)
- Default Branch: 3.x
- Last Pushed: 2024-11-06T04:22:42.000Z (8 months ago)
- Last Synced: 2024-12-30T21:15:29.636Z (6 months ago)
- Language: JavaScript
- Size: 369 KB
- Stars: 61
- Watchers: 12
- Forks: 26
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
- Security: SECURITY.md
Awesome Lists containing this project
README
# confit
[](https://travis-ci.org/krakenjs/confit)
Simple, environment-based configuration. `confit` loads a default JSON
configuration file, additionally loading environment-specific files, if applicable.
It will also process the loaded files using any configured
[shortstop](https://github.com/paypal/shortstop) protocol handlers—see **Options** below.
`confit` adds support for adding JavaScript-style comments in your json files as each file is processed by [shush](https://github.com/krakenjs/shush) before being merged into your config.
## Usage
```javascript
const confit = require('confit');
```
### confit([options])
* `options` (*String* | *Object*) - the base directory in which config files live or a configuration object. If no
arguments is provided, defaults to the directory of the calling file.
* returns - [config factory](#config-factory).
```javascript
'use strict';
const path = require('path');
const confit = require('confit');
const basedir = path.join(__dirname, 'config');
confit(basedir).create(function (err, config) {
config.get; // Function
config.set; // Function
config.use; // Function
config.get('env:env'); // 'development'
});
```
### config factory
* `addOverride(filepath)` (or) `addOverride(obj)` - Use this to add file (.json or .js), to merge with the config datastore and override the overlapping data if any. Alternatively, you can also pass a json object to override.
* `addDefault(filepath)` (or) `addDefault(obj)` - Use this to add default file (.json or .js), to merge with the config datastore and serve as the default datastore. Alternatively, you can also pass a json object for defaults.
* `create(callback)` - Creates the config object, ready for use. Callback signature: `function (err, config) {}`
```javascript
// All methods besides `create` are chainable
confit(options)
.addDefault('./mydefaults.json') //or .addDefault({foo: 'bar'})
.addOverride('./mysettings.json') //or .addOverride({foo: 'baz'})
.create(function (err, config) {
// ...
});
// - or -
//
// const factory = confit(options);
// factory.addOverride('./mysettings.json');
// factory.create(function (err, config) {
// // ...
// });
```
## Options
* `basedir` (*String*) - the base directory in which config files can be found.
* `protocols` (*Object*) - An object containing a mapping of
[shortstop](https://github.com/krakenjs/shortstop) protocols to either handler implementations or an array or handler implementations.
These protocols will be used to process the config data prior to registration.
If using an array of handler implementations, each handler is run in series (see [`Multiple handlers` in the shortstop README](https://github.com/krakenjs/shortstop#multiple-handlers)).
* `defaults` (*String*) - the name of the file containing all default values.
Defaults to `config.json`.
* `envignore` (*Array*) - any properties found in `process.env` that should be ignored
```javascript
'use strict';
const path = require('path');
const confit = require('confit');
const handlers = require('shortstop-handlers');
const options = {
basedir: path.join(__dirname, 'config'),
protocols: {
file: handlers.file(__dirname),
glob: handlers.glob(__dirname)
}
};
confit(options).create(function (err, config) {
// ...
});
```
## Config API
* `get(key)` - Retrieve the value for a given key. Colon-delimited keys can be used to traverse the object hierarchy.
* `set(key, value)` - Set a value for the given key. Colon-delimited keys can be used to traverse the object hierarchy.
* `use(obj)` - merge provided object into config.
```javascript
config.set('foo', 'bar');
config.get('foo'); // 'bar'
config.use({ foo: 'baz' });
config.get('foo'); // 'baz'
config.use({ a: { b: { c: 'd' } } } );
config.get('a:b:c'); // 'd'
```
## Default Behavior
By default, `confit` loads `process.env` and `argv` values upon initialization.
Additionally, it creates convenience environment properties prefixed with
`env:` based on the current `NODE_ENV` setting, defaulting to `development`. It
also normalizes `NODE_ENV` settings so values starting with `prod` become
`production`, starting with `stag` become `staging`, starting with `test`
become `test` and starting with `dev` become `development`.
```javascript
// NODE_ENV='dev'
config.get('NODE_ENV'); // 'dev'
config.get('env:env'); // 'development'
config.get('env:development'); // true
config.get('env:test'); // false
config.get('env:staging'); // false
config.get('env:production'); // false
```
```javascript
// NODE_ENV='custom'
config.get('NODE_ENV'); // 'custom'
config.get('env:env'); // 'custom'
config.get('env:development'); // false
config.get('env:test'); // false
config.get('env:staging'); // false
config.get('env:production'); // false
config.get('env:custom'); // true
```
#### Precedence
Precedence takes the following form (lower numbers overwrite higher numbers):
1. command line arguments
2. env variables
3. environment-specific config (e.g., `development.json`)
4. main config (`config.json`)
5. `env` normalization (`env`, `env:development`, etc)
#### Shortstop Handlers
Confit by default comes with 2 shortstop handlers enabled.
* `import:`
Merges the contents of the specified file into configuration under a given key.
```json
{
"foo": "import:./myjsonfile"
}
```
* `config:`
Replaces with the value at a given key. Note that the keys in this case are dot (.) delimited.
```json
{
"foo": {
"bar": true
},
"foobar": "config:foo.bar"
}
```