Node-config is a configuration system for Node.js application server deployments. It lets you define a default set of application parameters, and tune them for different runtime environments (development, qa, staging, production, etc.).
Parameters defined by node-config can be monitored and tuned at runtime without bouncing your production servers.
See the quick-start guide hosted on github
Node-config reads configuration files stored in the directory specified by the NODE_CONFIG_DIR environment variable, which defaults to the config directory within your top-level application directory. Configuration files can be in JavaScript format, JSON format, COFFEE format, or YAML format - whichever you prefer.
Configuration files in the config directory are loaded in the following order:
default.EXT
hostname.EXT
deployment.EXT
hostname-deployment.EXT
runtime.json
Where EXT can be .yml, .yaml, .coffee, .json, or .js depending on the format you prefer. NOTE: If you use .yml, .yaml, or .coffee file extensions, the 'yaml' or 'coffee-script' modules must be available. These external dependencies are not included from this package.
hostname is the $HOST environment variable if set, otherwise the $HOSTNAME environment variable if set, otherwise the hostname found from require('os').hostname(). Once a hostname is found, everything from the first period ('.') onwards is removed. For example, abc.example.com becomes abc
deployment is the deployment type, found in the $NODE_ENV environment variable. Defaults to 'development'.
The runtime.json file contains configuration changes made at runtime either manually, or by the application setting a configuration value. The location is specified by NODE_CONFIG_RUNTIME_JSON environment variable. By default, it is a file called runtime.json in NODE_CONFIG_DIR directory. Node-config monitors this file and loads any new configurations it detects. This file is loaded after all other configurations, including the $NODE_CONFIG environment variable and --NODE_CONFIG command line parameter (see below).
In the running application, each configuration parameter is internally monitored for changes, and persisted to runtime.json upon change. This keeps configurations in sync in a mutli-node deployment. If you want to disable this persistance and sync you can set the environment variable NODE_CONFIG_PERSIST_ON_CHANGE to "N". This will lead to lower I/O if you change variables very often in your application.
Javascript-style comments are stripped out of files before parsing, regardless of the file format type.
JSON files (.json) expose configuration parameters as a JSON object. Example:
/* Customer parameters
*
* This controls database access and legacy system synchronization
*/
{
"Customer": {
"dbName": "customers",
"dbHost": "localhost",
"dbPort": 5984
// Database synchronization frequency
"syncFrequency": 60
}
}
JavaScript files (.js) expose configuration parameters as module.exports. Example:
module.exports = {
Customer: {
dbName: "customers",
dbHost: "localhost",
dbPort: 5984,
creditLimit: 600 // Default initial credit limit
}
}
YAML files (.yaml or .yml) expose configuration parameters in YAML format. Example:
Customer:
dbName: customers
dbHost: localhost
dbPort: 5984
creditLimit: 600
Coffee-script files (.coffee) expose configuration parameters in coffee-script format. Example:
module.exports =
Customer:
dbName: "customers"
dbHost: "localhost"
dbPort: 5984
creditLimit: 600
When running multiple instances of your application, you may specify the $NODE_APP_INSTANCE environment variable prior to running your app. If set, this variable should contain an identifier for the specific instance of your app on this server, or within the network.
Configuration files appended with this identifier will be loaded after the configuration file without the instance identifier.
Example:
$ export NODE_ENV=staging
$ export NODE_APP_INSTANCE=3
$ node myApp.js
This instructs node-config to load default-3.json (if present) immediately after default.json, and staging-3.json after staging.json.
All configuration files (except runtime.json) follow this pattern, allowing your application to specify instance-specific configurations at any level.
If the $NODE_CONFIG environment variable is set, it must be a valid JSON string containing configuration overrides. These are applied after configuration files have been loaded.
For example, setting $NODE_CONFIG={"Customer":{"dbPort":5984}} will set the CONFIG.Customer.dbPort variable, overriding file configurations.
All environment variables described above may also be supplied on the command line.
Example:
$ node myApp.js --NODE_ENV=staging --NODE_APP_INSTANCE=3 '--NODE_CONFIG={"Customer":{"dbPort":5984}}'
The format must be two dashes followed by the environment variable name, an equals sign, and the value (as in the example above).
One important attribute of node-config is the ability to tune configuration parameters at runtime. Configuration parameters fall into one of the following categories:
Node-config is designed to run in a multi-node deployment, where many instances of your application are running on a production server (usually one per core processor).
If configuration values change at runtime, these changes are persisted into the runtime.json file within the config directory. Multi-node application instances keep in synch by watching for and loading changes in runtime.json when detected.
This paradigm does not extend beyond a single machine.
Module developers can use node-config to define module specific configuration parameters, and offer the same runtime tuning and multiple deployment capability as the local application.
Node.js modules don't live in the same directory as the application, so a different mechanism is offered to specify your default configuration.
The setModuleDefaults method creates an object (named after the module) within the CONFIG object containing all module configuration parameters, and their defaults.
Example:
var CONFIG = require("config");
CONFIG.setModuleDefaults("MyModule", {
templateName: "t-50",
colorScheme: "green"
});
Users of your module may override your defaults in their config/defaults file, or any of their deployment-specific configuration files.