1 | # confit
|
2 |
|
3 | [![Build Status](https://travis-ci.org/krakenjs/confit.svg?branch=2.x)](https://travis-ci.org/krakenjs/confit)
|
4 |
|
5 | Simple, environment-based configuration. `confit` loads a default JSON
|
6 | configuration file, additionally loading environment-specific files, if applicable.
|
7 | It will also process the loaded files using any configured
|
8 | [shortstop](https://github.com/paypal/shortstop) protocol handlers—see **Options** below.
|
9 |
|
10 | `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.
|
11 |
|
12 |
|
13 | ## Usage
|
14 | ```javascript
|
15 | var confit = require('confit');
|
16 | ```
|
17 |
|
18 | ### confit([options])
|
19 | * `options` (*String* | *Object*) - the base directory in which config files live or a configuration object. If no
|
20 | arguments is provided, defaults to the directory of the calling file.
|
21 | * returns - [config factory](#config-factory).
|
22 |
|
23 | ```javascript
|
24 | 'use strict';
|
25 |
|
26 | var path = require('path');
|
27 | var confit = require('confit');
|
28 |
|
29 | var basedir = path.join(__dirname, 'config');
|
30 | confit(basedir).create(function (err, config) {
|
31 | config.get; // Function
|
32 | config.set; // Function
|
33 | config.use; // Function
|
34 |
|
35 | config.get('env:env'); // 'development'
|
36 | });
|
37 | ```
|
38 |
|
39 | ### config factory
|
40 | * `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.
|
41 | * `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.
|
42 | * `create(callback)` - Creates the config object, ready for use. Callback signature: `function (err, config) {}`
|
43 |
|
44 | ```javascript
|
45 | // All methods besides `create` are chainable
|
46 | confit(options)
|
47 | .addDefault('./mydefaults.json') //or .addDefault({foo: 'bar'})
|
48 | .addOverride('./mysettings.json') //or .addOverride({foo: 'baz'})
|
49 | .create(function (err, config) {
|
50 | // ...
|
51 | });
|
52 |
|
53 | // - or -
|
54 | //
|
55 | // var factory = confit(options);
|
56 | // factory.addOverride('./mysettings.json');
|
57 | // factory.create(function (err, config) {
|
58 | // // ...
|
59 | // });
|
60 | ```
|
61 |
|
62 | ## Options
|
63 | * `basedir` (*String*) - the base directory in which config files can be found.
|
64 | * `protocols` (*Object*) - An object containing a mapping of
|
65 | [shortstop](https://github.com/krakenjs/shortstop) protocols to either handler implementations or an array or handler implementations.
|
66 | These protocols will be used to process the config data prior to registration.
|
67 | 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)).
|
68 | * `defaults` (*String*) - the name of the file containing all default values.
|
69 | Defaults to `config.json`.
|
70 | * `envignore` (*Array*) - any properties found in `process.env` that should be ignored
|
71 |
|
72 | ```javascript
|
73 | 'use strict';
|
74 |
|
75 | var path = require('path');
|
76 | var confit = require('confit');
|
77 | var handlers = require('shortstop-handlers');
|
78 |
|
79 |
|
80 | var options = {
|
81 | basedir: path.join(__dirname, 'config'),
|
82 | protocols: {
|
83 | file: handlers.file(__dirname),
|
84 | glob: handlers.glob(__dirname)
|
85 | }
|
86 | };
|
87 |
|
88 | confit(options).create(function (err, config) {
|
89 | // ...
|
90 | });
|
91 | ```
|
92 |
|
93 |
|
94 | ## Config API
|
95 | * `get(key)` - Retrieve the value for a given key. Colon-delimited keys can be used to traverse the object hierarchy.
|
96 | * `set(key, value)` - Set a value for the given key. Colon-delimited keys can be used to traverse the object hierarchy.
|
97 | * `use(obj)` - merge provided object into config.
|
98 |
|
99 | ```javascript
|
100 | config.set('foo', 'bar');
|
101 | config.get('foo'); // 'bar'
|
102 |
|
103 | config.use({ foo: 'baz' });
|
104 | config.get('foo'); // 'baz'
|
105 |
|
106 | config.use({ a: { b: { c: 'd' } } } );
|
107 | config.get('a:b:c'); // 'd'
|
108 | ```
|
109 |
|
110 | ## Default Behavior
|
111 | By default, `confit` loads `process.env` and `argv` values upon initialization.
|
112 | Additionally, it creates convenience environment properties prefixed with
|
113 | `env:` based on the current `NODE_ENV` setting, defaulting to `development`. It
|
114 | also normalizes `NODE_ENV` settings so values starting with `prod` become
|
115 | `production`, starting with `stag` become `staging`, starting with `test`
|
116 | become `test` and starting with `dev` become `development`.
|
117 |
|
118 | ```javascript
|
119 | // NODE_ENV='dev'
|
120 | config.get('NODE_ENV'); // 'dev'
|
121 | config.get('env:env'); // 'development'
|
122 | config.get('env:development'); // true
|
123 | config.get('env:test'); // false
|
124 | config.get('env:staging'); // false
|
125 | config.get('env:production'); // false
|
126 | ```
|
127 |
|
128 | ```javascript
|
129 | // NODE_ENV='custom'
|
130 | config.get('NODE_ENV'); // 'custom'
|
131 | config.get('env:env'); // 'custom'
|
132 | config.get('env:development'); // false
|
133 | config.get('env:test'); // false
|
134 | config.get('env:staging'); // false
|
135 | config.get('env:production'); // false
|
136 | config.get('env:custom'); // true
|
137 | ```
|
138 | #### Precedence
|
139 |
|
140 | Precedence takes the following form (lower numbers overwrite higher numbers):
|
141 |
|
142 | 1. command line arguments
|
143 | 2. env variables
|
144 | 3. environment-specific config (e.g., `development.json`)
|
145 | 4. main config (`config.json`)
|
146 | 5. `env` normalization (`env`, `env:development`, etc)
|
147 |
|
148 | #### Shortstop Handlers
|
149 |
|
150 | Confit by default comes with 2 shortstop handlers enabled.
|
151 |
|
152 | * `import:`
|
153 | Merges the contents of the specified file into configuration under a given key.
|
154 | ```json
|
155 | {
|
156 | "foo": "import:./myjsonfile"
|
157 | }
|
158 | ```
|
159 |
|
160 | * `config:`
|
161 | Replaces with the value at a given key. Note that the keys in this case are dot (.) delimited.
|
162 | ```json
|
163 | {
|
164 | "foo": {
|
165 | "bar": true
|
166 | },
|
167 | "foobar": "config:foo.bar"
|
168 | }
|
169 | ```
|