node-configure

There are several configuration modules available for node.js. Each have their strengths and weaknesses, but no one project can be considered the optimal configuration option for all use cases. Some applications have need of complex configuration that can be fetched from a central server. Others just want a simple JSON object loaded when the app starts.

node-configure seeks to solve the problem of a single application that is being developed by a group of developers who need the ability to have a different application configuration for each developer and deployment environment, but do not wish to utilize a complex configuration module.

Using node-configure, each developer can have a separate configuration file checked in to source control without being forced to worry about overwrites from another developer.

Overview

node-configure is designed to provide a global config that can be obtained from any node application file without forcing the main app file to load and pass around configuration setting objects. With node-configure, any file or module that requires the node-configure module will receive the same configuration object, which is the parsed result of the JSON configuration file.

With node-configure, it is the responsibility of modules that wish to obtain configuration settings to know their appropriate configuration fields and to provide defaults as necessary.

Example

The following is an example of how one might use the node-configure module.

The myConfig.json file:

{
    "serverPort" : 3000,
    "couchDb" : {
        "host" : "localhost",
        "port" : 5984,
    }
}

The main.js file:

var config = require("configure");
var port = 2000; // default port
if(config.serverPort) {
    port = config.serverPort;
}
// elsewhere...
server.listen(port, requestHandler);

The database.js file:

var config = require("configure");
var request = { "host":"my.couchdb.com", "port":5984 };
if(config.couchDb) {
    if(config.couchDb.host) {
        request.host = config.couchDb.host;
    }
    if(config.couchDb.port) {
        request.port = config.couchDb.port;
    }
}
// later...
request.path = "/mydata";
http.get(request, responseHandler);

The node start script:

node main.js --config myConfig.json

The Config File

At present node-configure only supports JSON configuration files.

Default Behavior

The first time the node-configure module is required by an application, it will attempt to load the file specified by the --config switch relative to the current working directory as obtained via process.cwd(). If node-configure fails to find or load the file, it will throw an exception.

If the --config switch is not included as a command line parameter, node-configure will attempt to load the file "config.json" in the current working directory. If that file is not found, node-configure will throw an exception.

Changing Default Behavior

node-configure makes use of npm's package-level configuration system. If you wish to change the default behavior of node-configure you may do so through this system. After changing a package configuration option via npm config set, you must restart the node-configure package to use the new settings. For example:

npm config set configure:notFound throw

npm restart configure

node-configure supports the following npm configuration keys:

• notFound: specifies what node-configure should do when it fails to load a configuration file. Set this value to "throw" to cause node-configure to throw an exception on a failed load. Any other value will cause node-configure to return null when it fails to load a configuration file.
• defaultConfigFile: specifies the file node-configure should attempt to load if no file is specified via command line.
• commandLineSwitchName: specifies the command line switch node-configure should look for to determine which configuration file to load. Change this value if you or some other module already use --config