Node.js Configuration

Node.js Configuration
Search:
 
Filters

Online Documentation

Introduction

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.

Project Guidelines

  • Simple - Get started fast
  • Predictable - Well tested and stable
  • Flexible - Reasonable defaults & hackable
  • Powerful - For multi-node enterprise deployment
  • Easy Integration - For module developers

Getting Started

See the quick-start guide hosted on github

Configuration Files

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
    local.EXT
    local-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 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. 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.

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.

File Comments

Javascript-style comments are stripped out of files before parsing, regardless of the file format type.

File Formats

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
  

Monitoring Changes

One important attribute of node-config is the ability to tune configuration parameters at runtime. Configuration parameters fall into one of the following categories:

  • OK to change - This parameter type can change without adverse effect. Most parameters fall into this category, where the parameter value is read every time it's used.
  • Monitored - Some parameters are read infrequently (usually at the start of the application), and need to be monitored for change. The CONFIG.watch() function is available to watch these parameters, and run a function when the value changes. See the watch method definition for more information.
  • Not OK to change - Some parameters must be fixed at runtime and remain stable throughout the lifecycle of the application. For these parameters, the makeImmutable method is offered to guarantee the parameter cannot be changed.

Production Deployments

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.

For Module Developers

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.

Online docs built by yui-doc and hosted by github.


Released on github under the Apache License 2.0 version 0.4.21