1 | Configure your Node.js Applications
|
2 | ===================================
|
3 |
|
4 | [![NPM](https://nodei.co/npm/config.svg?downloads=true&downloadRank=true)](https://nodei.co/npm/config/)
|
5 | [![Build Status](https://secure.travis-ci.org/lorenwest/node-config.svg?branch=master)](https://travis-ci.org/lorenwest/node-config)
|
6 | [release notes](https://github.com/lorenwest/node-config/blob/master/History.md)
|
7 |
|
8 | Introduction
|
9 | ------------
|
10 |
|
11 | Node-config organizes hierarchical configurations for your app deployments.
|
12 |
|
13 | It lets you define a set of default parameters,
|
14 | and extend them for different deployment environments (development, qa,
|
15 | staging, production, etc.).
|
16 |
|
17 | Configurations are stored in [configuration files](https://github.com/lorenwest/node-config/wiki/Configuration-Files) within your application, and can be overridden and extended by [environment variables](https://github.com/lorenwest/node-config/wiki/Environment-Variables),
|
18 | [command line parameters](https://github.com/lorenwest/node-config/wiki/Command-Line-Overrides), or [external sources](https://github.com/lorenwest/node-config/wiki/Configuring-from-an-External-Source).
|
19 |
|
20 | This gives your application a consistent configuration interface shared among a
|
21 | [growing list of npm modules](https://www.npmjs.org/browse/depended/config) also using node-config.
|
22 |
|
23 | Project Guidelines
|
24 | ------------------
|
25 |
|
26 | * *Simple* - Get started fast
|
27 | * *Powerful* - For multi-node enterprise deployment
|
28 | * *Flexible* - Supporting multiple config file formats
|
29 | * *Lightweight* - Small file and memory footprint
|
30 | * *Predictable* - Well tested foundation for module and app developers
|
31 |
|
32 | Quick Start
|
33 | ---------------
|
34 | The following examples are in JSON format, but configurations can be in other [file formats](https://github.com/lorenwest/node-config/wiki/Configuration-Files#file-formats).
|
35 |
|
36 | **Install in your app directory, and edit the default config file.**
|
37 |
|
38 | ```shell
|
39 | $ npm install config
|
40 | $ mkdir config
|
41 | $ vi config/default.json
|
42 | ```
|
43 | ```js
|
44 | {
|
45 | // Customer module configs
|
46 | "Customer": {
|
47 | "dbConfig": {
|
48 | "host": "localhost",
|
49 | "port": 5984,
|
50 | "dbName": "customers"
|
51 | },
|
52 | "credit": {
|
53 | "initialLimit": 100,
|
54 | // Set low for development
|
55 | "initialDays": 1
|
56 | }
|
57 | }
|
58 | }
|
59 | ```
|
60 |
|
61 | **Edit config overrides for production deployment:**
|
62 |
|
63 | ```shell
|
64 | $ vi config/production.json
|
65 | ```
|
66 |
|
67 | ```json
|
68 | {
|
69 | "Customer": {
|
70 | "dbConfig": {
|
71 | "host": "prod-db-server"
|
72 | },
|
73 | "credit": {
|
74 | "initialDays": 30
|
75 | }
|
76 | }
|
77 | }
|
78 | ```
|
79 |
|
80 | **Use configs in your code:**
|
81 |
|
82 | ```js
|
83 | const config = require('config');
|
84 | //...
|
85 | const dbConfig = config.get('Customer.dbConfig');
|
86 | db.connect(dbConfig, ...);
|
87 |
|
88 | if (config.has('optionalFeature.detail')) {
|
89 | const detail = config.get('optionalFeature.detail');
|
90 | //...
|
91 | }
|
92 | ```
|
93 |
|
94 | `config.get()` will throw an exception for undefined keys to help catch typos and missing values.
|
95 | Use `config.has()` to test if a configuration value is defined.
|
96 |
|
97 | **Start your app server:**
|
98 |
|
99 | ```shell
|
100 | $ export NODE_ENV=production
|
101 | $ node my-app.js
|
102 | ```
|
103 |
|
104 | Running in this configuration, the `port` and `dbName` elements of `dbConfig`
|
105 | will come from the `default.json` file, and the `host` element will
|
106 | come from the `production.json` override file.
|
107 |
|
108 | Articles
|
109 | --------
|
110 |
|
111 | * [Configuration Files](https://github.com/lorenwest/node-config/wiki/Configuration-Files)
|
112 | * [Special features for JavaScript configuration files](https://github.com/lorenwest/node-config/wiki/Special-features-for-JavaScript-configuration-files)
|
113 | * [Common Usage](https://github.com/lorenwest/node-config/wiki/Common-Usage)
|
114 | * [Environment Variables](https://github.com/lorenwest/node-config/wiki/Environment-Variables)
|
115 | * [Reserved Words](https://github.com/lorenwest/node-config/wiki/Reserved-Words)
|
116 | * [Command Line Overrides](https://github.com/lorenwest/node-config/wiki/Command-Line-Overrides)
|
117 | * [Multiple Node Instances](https://github.com/lorenwest/node-config/wiki/Multiple-Node-Instances)
|
118 | * [Sub-Module Configuration](https://github.com/lorenwest/node-config/wiki/Sub-Module-Configuration)
|
119 | * [Configuring from a DB / External Source](https://github.com/lorenwest/node-config/wiki/Configuring-from-an-External-Source)
|
120 | * [Securing Production Config Files](https://github.com/lorenwest/node-config/wiki/Securing-Production-Config-Files)
|
121 | * [External Configuration Management Tools](https://github.com/lorenwest/node-config/wiki/External-Configuration-Management-Tools)
|
122 | * [Examining Configuration Sources](https://github.com/lorenwest/node-config/wiki/Examining-Configuration-Sources)
|
123 | * [Using Config Utilities](https://github.com/lorenwest/node-config/wiki/Using-Config-Utilities)
|
124 | * [Upgrading from Config 0.x](https://github.com/lorenwest/node-config/wiki/Upgrading-From-Config-0.x)
|
125 | * [Webpack usage](https://github.com/lorenwest/node-config/wiki/Webpack-Usage)
|
126 |
|
127 | Further Information
|
128 | ---------------------
|
129 | If you still don't see what you are looking for, here are some more resources to check:
|
130 |
|
131 | * The [wiki may have more pages](https://github.com/lorenwest/node-config/wiki) which are not directly linked from here.
|
132 | * Review [questions tagged with node-config](https://stackexchange.com/filters/207096/node-config) on StackExchange. These are monitored by `node-config` contributors.
|
133 | * [Search the issue tracker](https://github.com/lorenwest/node-config/issues). Hundreds of issues have already been discussed and resolved there.
|
134 |
|
135 | Contributors
|
136 | ------------
|
137 | <table id="contributors"><tr><td><img src=https://avatars2.githubusercontent.com/u/373538?v=4><a href="https://github.com/lorenwest">lorenwest</a></td>
|
138 | <td><img src=https://avatars1.githubusercontent.com/u/25829?v=4><a href="https://github.com/markstos">markstos</a></td>
|
139 | <td><img src=https://avatars1.githubusercontent.com/u/1083065?v=4><a href="https://github.com/iMoses">iMoses</a></td>
|
140 | <td><img src=https://avatars3.githubusercontent.com/u/447151?v=4><a href="https://github.com/elliotttf">elliotttf</a></td>
|
141 | <td><img src=https://avatars1.githubusercontent.com/u/8839447?v=4><a href="https://github.com/jfelege">jfelege</a></td>
|
142 | <td><img src=https://avatars0.githubusercontent.com/u/66902?v=4><a href="https://github.com/leachiM2k">leachiM2k</a></td>
|
143 | </tr><tr><td><img src=https://avatars1.githubusercontent.com/u/791137?v=4><a href="https://github.com/josx">josx</a></td>
|
144 | <td><img src=https://avatars2.githubusercontent.com/u/133277?v=4><a href="https://github.com/enyo">enyo</a></td>
|
145 | <td><img src=https://avatars1.githubusercontent.com/u/4307697?v=4><a href="https://github.com/leosuncin">leosuncin</a></td>
|
146 | <td><img src=https://avatars3.githubusercontent.com/u/1077378?v=4><a href="https://github.com/arthanzel">arthanzel</a></td>
|
147 | <td><img src=https://avatars2.githubusercontent.com/u/1656140?v=4><a href="https://github.com/eheikes">eheikes</a></td>
|
148 | <td><img src=https://avatars3.githubusercontent.com/u/138707?v=4><a href="https://github.com/th507">th507</a></td>
|
149 | </tr><tr><td><img src=https://avatars2.githubusercontent.com/u/506460?v=4><a href="https://github.com/Osterjour">Osterjour</a></td>
|
150 | <td><img src=https://avatars3.githubusercontent.com/u/1751645?v=4><a href="https://github.com/cunneen">cunneen</a></td>
|
151 | <td><img src=https://avatars0.githubusercontent.com/u/842998?v=4><a href="https://github.com/nsabovic">nsabovic</a></td>
|
152 | <td><img src=https://avatars0.githubusercontent.com/u/5138570?v=4><a href="https://github.com/BadgerBadgerBadgerBadger">BadgerBadgerBadgerBadger</a></td>
|
153 | <td><img src=https://avatars2.githubusercontent.com/u/2529835?v=4><a href="https://github.com/simon-scherzinger">simon-scherzinger</a></td>
|
154 | <td><img src=https://avatars3.githubusercontent.com/u/8650543?v=4><a href="https://github.com/leonardovillela">leonardovillela</a></td>
|
155 | </tr><tr><td><img src=https://avatars1.githubusercontent.com/u/175627?v=4><a href="https://github.com/axelhzf">axelhzf</a></td>
|
156 | <td><img src=https://avatars3.githubusercontent.com/u/7782055?v=4><a href="https://github.com/benkroeger">benkroeger</a></td>
|
157 | <td><img src=https://avatars3.githubusercontent.com/u/1872824?v=4><a href="https://github.com/fgheorghe">fgheorghe</a></td>
|
158 | <td><img src=https://avatars3.githubusercontent.com/u/1443067?v=4><a href="https://github.com/IvanVergiliev">IvanVergiliev</a></td>
|
159 | <td><img src=https://avatars0.githubusercontent.com/u/1736957?v=4><a href="https://github.com/jpwilliams">jpwilliams</a></td>
|
160 | <td><img src=https://avatars2.githubusercontent.com/u/1246875?v=4><a href="https://github.com/jaylynch">jaylynch</a></td>
|
161 | </tr><tr><td><img src=https://avatars1.githubusercontent.com/u/145742?v=4><a href="https://github.com/jberrisch">jberrisch</a></td>
|
162 | <td><img src=https://avatars1.githubusercontent.com/u/9355665?v=4><a href="https://github.com/kgoerlitz">kgoerlitz</a></td>
|
163 | <td><img src=https://avatars0.githubusercontent.com/u/8525267?v=4><a href="https://github.com/bertho-zero">bertho-zero</a></td>
|
164 | <td><img src=https://avatars3.githubusercontent.com/u/1918551?v=4><a href="https://github.com/nitzan-shaked">nitzan-shaked</a></td>
|
165 | <td><img src=https://avatars3.githubusercontent.com/u/3058150?v=4><a href="https://github.com/robertrossmann">robertrossmann</a></td>
|
166 | <td><img src=https://avatars2.githubusercontent.com/u/498929?v=4><a href="https://github.com/roncli">roncli</a></td>
|
167 | </tr></table>
|
168 |
|
169 | License
|
170 | -------
|
171 |
|
172 | May be freely distributed under the [MIT license](https://raw.githubusercontent.com/lorenwest/node-config/master/LICENSE).
|
173 |
|
174 | Copyright (c) 2010-2020 Loren West
|
175 | [and other contributors](https://github.com/lorenwest/node-config/graphs/contributors)
|
176 |
|