Node.js Configuration

Get Command Line Arguments

This method allows you to retrieve the value of the specified command line argument.

The argument is case sensitive, and must be of the form '--ARG_NAME=value'

Parameters:

searchFor <STRING> The argument name to search for

Returns: MIXED

FALSE if the argument was not found, the argument value if found

Initialize a parameter from the command line or process environment

This method looks for the parameter from the command line in the format --PARAMETER=VALUE, then from the process environment, then from the default specified as an argument.

Parameters:

paramName <String> Name of the parameter

[defaultValue] <Any> Default value of the parameter

Returns: Any

The found value, or default value

Get the configuration object.

The configuration object is a shared singleton object within the applicaiton, attained by calling require('config').

Usually you'll specify a CONFIG variable at the top of your .js file for file/module scope. If you want the root of the object, you can do this:

var CONFIG = require('config');

Sometimes you only care about a specific sub-object within the CONFIG object. In that case you could do this at the top of your file:

var CONFIG = require('config').customer;
or
var CUSTOMER_CONFIG = require('config').customer;

Returns: object

CONFIG - The top level configuration object

All sources for configurations are stored in an array of objects containing the source name (usually the filaname), the original source (as a string), and the parsed source as an object.

Returns: Array[Object]

configSources - An array of objects containing name, original, and parsed elements

Exposing original Config

This method allows get the original config properties.

Returns: object

The original config object is returned

Make a configuration property hidden so it doesn't appear when enumerating elements of the object.

The property still exists and can be read from and written to, but it won't show up in for ... in loops, Object.keys(), or JSON.stringify() type methods.

If the property already exists, it will be made hidden. Otherwise it will be created as a hidden property with the specified value.

This method was built for hiding configuration values, but it can be applied to any javascript object.

Example:

var CONFIG = require('config');
...
// Hide the Amazon S3 credentials
CONFIG.makeHidden(CONFIG.amazonS3, 'access_id');
CONFIG.makeHidden(CONFIG.amazonS3, 'secret_key');

Parameters:

object <object> - The object to make a hidden property into.

property <string> - The name of the property to make hidden.

value <mixed> - (optional) Set the property value to this (otherwise leave alone)

Returns: object

object - The original object is returned - for chaining.

Make a configuration property immutable (assuring it cannot be changed from the current value).

This operation cannot be un-done.

This method was built for disabling runtime changes to configuration values, but it can be applied to any javascript object.

Example:

var CONFIG = require('config').customer;
...
// Obtain a DB connection using CONFIG parameters
database.open(CONFIG.db.name, CONFIG.db.port);
...
// Don't allow database changes after connect
CONFIG.makeImmutable(CONFIG.db, 'name');
CONFIG.makeImmutable(CONFIG.db, 'port');

Parameters:

object <object> - The object to attach an immutable property into.

property <string> - The name of the property to make immutable.

value <mixed> - (optional) Set the property value to this (otherwise leave alone)

Returns: object

object - The original object is returned - for chaining.

Reset Runtime Config

This method allows you to reset the runtime.json generated file.

Parameters:

callback <function> An optional callback function

Returns: void

Set default configurations for a node.js module.

This allows module developers to attach their configurations onto the default configuration object so they can be configured by the consumers of the module.

Using the function within your module:

var CONFIG = require("config");
CONFIG.setModuleDefaults("MyModule", {
  templateName: "t-50",
  colorScheme: "green"
});


// Template name may be overridden by application config files
console.log("Template: " + CONFIG.MyModule.templateName);

The above example results in a "MyModule" element of the configuration object, containing an object with the specified default values.

Parameters:

moduleName <string> - Name of your module.

defaultProperties <object> - The default module configuration.

Returns: object

moduleConfig - The module level configuration object.

Monitor a configuration value for runtime changes.

Configuration values can be changed at runtime by the application or by a manual change to the config/runtime.json file. This method lets you specify a function to run when a configuration value changes.

This was built for monitoring changes to configuration values, but it can be used for watching changes to any javascript object.

Example:

var CONFIG = require('config').customer;
...
// Watch for any changes to the customer configuration
CONFIG.watch(CONFIG, null, function(object, propertyName, priorValue, newValue) {
 console.log("Customer configuration " + propertyName + " changed from " + priorValue + " to " + newValue);
});

Parameters:

object <object> - The object to watch.

property <string> - The property name to watch. Watch all object properties if null.

handler <function(object, propertyName, priorValue, newValue)> - Handler called when a property change is detected. The handler is run along with other handlers registered for notification. If your handler changes the value of the property, that change is applied after all handlers have finished processing the current change. Then all handlers (including this one) will be called again with the newly changed value.

depth <integer> (optional) - If watching all object properties or if the specified property is an object, this specifies the depth of the object graph to watch for changes. Default 6.

Returns: object

object - The original object is returned - for chaining.

Node-config automatically monitors and apply changes made to the config/runtime.json file. This paradigm allows for manual changes to running application servers, and for multi-node application servers to keep in sync.

This method allows you to change the polling interval from the default interval (2.5 seconds), or to turn file watching off. On Linux systems with inotify, and in node.js versions 0.6 and above, this interval is ignored.

runtime.json file watching can be disabled by setting the NODE_CONFIG_DISABLE_FILE_WATCH environment variable or --NODE_CONFIG_DISABLE_FILE_WATCH command line parameter to "Y" prior to running your application.

Parameters:

interval <Integer> - Polling interval in milliseconds. Defaults to 2500.

Returns: void