1 | # rc
|
2 |
|
3 | The non-configurable configuration loader for lazy people.
|
4 |
|
5 | ## Usage
|
6 |
|
7 | The only option is to pass rc the name of your app, and your default configuration.
|
8 |
|
9 | ```javascript
|
10 | var conf = require('rc')(appname, {
|
11 | //defaults go here.
|
12 | port: 2468,
|
13 |
|
14 | //defaults which are objects will be merged, not replaced
|
15 | views: {
|
16 | engine: 'jade'
|
17 | }
|
18 | });
|
19 | ```
|
20 |
|
21 | `rc` will return your configuration options merged with the defaults you specify.
|
22 | If you pass in a predefined defaults object, it will be mutated:
|
23 |
|
24 | ```javascript
|
25 | var conf = {};
|
26 | require('rc')(appname, conf);
|
27 | ```
|
28 |
|
29 | If `rc` finds any config files for your app, the returned config object will have
|
30 | a `configs` array containing their paths:
|
31 |
|
32 | ```javascript
|
33 | var appCfg = require('rc')(appname, conf);
|
34 | appCfg.configs[0] // /etc/appnamerc
|
35 | appCfg.configs[1] // /home/dominictarr/.config/appname
|
36 | appCfg.config // same as appCfg.configs[appCfg.configs.length - 1]
|
37 | ```
|
38 |
|
39 | ## Standards
|
40 |
|
41 | Given your application name (`appname`), rc will look in all the obvious places for configuration.
|
42 |
|
43 | * command line arguments, parsed by minimist _(e.g. `--foo baz`, also nested: `--foo.bar=baz`)_
|
44 | * environment variables prefixed with `${appname}_`
|
45 | * or use "\_\_" to indicate nested properties <br/> _(e.g. `appname_foo__bar__baz` => `foo.bar.baz`)_
|
46 | * if you passed an option `--config file` then from that file
|
47 | * a local `.${appname}rc` or the first found looking in `./ ../ ../../ ../../../` etc.
|
48 | * `$HOME/.${appname}rc`
|
49 | * `$HOME/.${appname}/config`
|
50 | * `$HOME/.config/${appname}`
|
51 | * `$HOME/.config/${appname}/config`
|
52 | * `/etc/${appname}rc`
|
53 | * `/etc/${appname}/config`
|
54 | * the defaults object you passed in.
|
55 |
|
56 | All configuration sources that were found will be flattened into one object,
|
57 | so that sources **earlier** in this list override later ones.
|
58 |
|
59 |
|
60 | ## Configuration File Formats
|
61 |
|
62 | Configuration files (e.g. `.appnamerc`) may be in either [json](http://json.org/example) or [ini](http://en.wikipedia.org/wiki/INI_file) format. **No** file extension (`.json` or `.ini`) should be used. The example configurations below are equivalent:
|
63 |
|
64 |
|
65 | #### Formatted as `ini`
|
66 |
|
67 | ```
|
68 | ; You can include comments in `ini` format if you want.
|
69 |
|
70 | dependsOn=0.10.0
|
71 |
|
72 |
|
73 | ; `rc` has built-in support for ini sections, see?
|
74 |
|
75 | [commands]
|
76 | www = ./commands/www
|
77 | console = ./commands/repl
|
78 |
|
79 |
|
80 | ; You can even do nested sections
|
81 |
|
82 | [generators.options]
|
83 | engine = ejs
|
84 |
|
85 | [generators.modules]
|
86 | new = generate-new
|
87 | engine = generate-backend
|
88 |
|
89 | ```
|
90 |
|
91 | #### Formatted as `json`
|
92 |
|
93 | ```javascript
|
94 | {
|
95 | // You can even comment your JSON, if you want
|
96 | "dependsOn": "0.10.0",
|
97 | "commands": {
|
98 | "www": "./commands/www",
|
99 | "console": "./commands/repl"
|
100 | },
|
101 | "generators": {
|
102 | "options": {
|
103 | "engine": "ejs"
|
104 | },
|
105 | "modules": {
|
106 | "new": "generate-new",
|
107 | "backend": "generate-backend"
|
108 | }
|
109 | }
|
110 | }
|
111 | ```
|
112 |
|
113 | Comments are stripped from JSON config via [strip-json-comments](https://github.com/sindresorhus/strip-json-comments).
|
114 |
|
115 | > Since ini, and env variables do not have a standard for types, your application needs be prepared for strings.
|
116 |
|
117 | To ensure that string representations of booleans and numbers are always converted into their proper types (especially useful if you intend to do strict `===` comparisons), consider using a module such as [parse-strings-in-object](https://github.com/anselanza/parse-strings-in-object) to wrap the config object returned from rc.
|
118 |
|
119 |
|
120 | ## Simple example demonstrating precedence
|
121 | Assume you have an application like this (notice the hard-coded defaults passed to rc):
|
122 | ```
|
123 | const conf = require('rc')('myapp', {
|
124 | port: 12345,
|
125 | mode: 'test'
|
126 | });
|
127 |
|
128 | console.log(JSON.stringify(conf, null, 2));
|
129 | ```
|
130 | You also have a file `config.json`, with these contents:
|
131 | ```
|
132 | {
|
133 | "port": 9000,
|
134 | "foo": "from config json",
|
135 | "something": "else"
|
136 | }
|
137 | ```
|
138 | And a file `.myapprc` in the same folder, with these contents:
|
139 | ```
|
140 | {
|
141 | "port": "3001",
|
142 | "foo": "bar"
|
143 | }
|
144 | ```
|
145 | Here is the expected output from various commands:
|
146 |
|
147 | `node .`
|
148 | ```
|
149 | {
|
150 | "port": "3001",
|
151 | "mode": "test",
|
152 | "foo": "bar",
|
153 | "_": [],
|
154 | "configs": [
|
155 | "/Users/stephen/repos/conftest/.myapprc"
|
156 | ],
|
157 | "config": "/Users/stephen/repos/conftest/.myapprc"
|
158 | }
|
159 | ```
|
160 | *Default `mode` from hard-coded object is retained, but port is overridden by `.myapprc` file (automatically found based on appname match), and `foo` is added.*
|
161 |
|
162 |
|
163 | `node . --foo baz`
|
164 | ```
|
165 | {
|
166 | "port": "3001",
|
167 | "mode": "test",
|
168 | "foo": "baz",
|
169 | "_": [],
|
170 | "configs": [
|
171 | "/Users/stephen/repos/conftest/.myapprc"
|
172 | ],
|
173 | "config": "/Users/stephen/repos/conftest/.myapprc"
|
174 | }
|
175 | ```
|
176 | *Same result as above but `foo` is overridden because command-line arguments take precedence over `.myapprc` file.*
|
177 |
|
178 | `node . --foo barbar --config config.json`
|
179 | ```
|
180 | {
|
181 | "port": 9000,
|
182 | "mode": "test",
|
183 | "foo": "barbar",
|
184 | "something": "else",
|
185 | "_": [],
|
186 | "config": "config.json",
|
187 | "configs": [
|
188 | "/Users/stephen/repos/conftest/.myapprc",
|
189 | "config.json"
|
190 | ]
|
191 | }
|
192 | ```
|
193 | *Now the `port` comes from the `config.json` file specified (overriding the value from `.myapprc`), and `foo` value is overriden by command-line despite also being specified in the `config.json` file.*
|
194 |
|
195 |
|
196 |
|
197 | ## Advanced Usage
|
198 |
|
199 | #### Pass in your own `argv`
|
200 |
|
201 | You may pass in your own `argv` as the third argument to `rc`. This is in case you want to [use your own command-line opts parser](https://github.com/dominictarr/rc/pull/12).
|
202 |
|
203 | ```javascript
|
204 | require('rc')(appname, defaults, customArgvParser);
|
205 | ```
|
206 |
|
207 | ## Pass in your own parser
|
208 |
|
209 | If you have a special need to use a non-standard parser,
|
210 | you can do so by passing in the parser as the 4th argument.
|
211 | (leave the 3rd as null to get the default args parser)
|
212 |
|
213 | ```javascript
|
214 | require('rc')(appname, defaults, null, parser);
|
215 | ```
|
216 |
|
217 | This may also be used to force a more strict format,
|
218 | such as strict, valid JSON only.
|
219 |
|
220 | ## Note on Performance
|
221 |
|
222 | `rc` is running `fs.statSync`-- so make sure you don't use it in a hot code path (e.g. a request handler)
|
223 |
|
224 |
|
225 | ## License
|
226 |
|
227 | Multi-licensed under the two-clause BSD License, MIT License, or Apache License, version 2.0
|