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