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 .js 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 .yaml, .coffee, .json, or .js depending on the format you prefer. NOTE: If you use .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 found from require('os').hostname()
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. Node-config monitors this file and loads any new configurations it detects.
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.
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) 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
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 a few 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 this file 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.
Users of your module may override your defaults in their config/defaults file, or any of their deployment-specific configuration files.