Fork me on GitHub


A tool for describing application configurations!


Convention and Configuration

Confab is configuration-first by nature, as the details of configuration may vary widely from one project to the next. Nevertheless, the built-in transformations reflect certain opinions.

Namely, configuration should be:

And one non-opinion

confab (definition)

Build a configuration object from a list of transformations:

 var confab = require('confab');
 var config = confab([
     './config.' + process.env.NODE_ENV + '.json',

     role: 'api',
     port: 3200

Later, access the configuration exactly as you would expect.

 console.log(config.role); // 'api'


Type Name Description
Array transforms a list of transformation functions

loadJSON (definition)

Load a configuration from a list of candidate files.

Extends the configuration with the contents of the configuration file at the first matched path, falling back to subsequent paths if the first cannot be found. Throws a ReferenceError if none of the specified paths are matched.

var loadJSONTransform = confab.loadJSON([
  __dirname + '/config.json',
  process.env.HOME + '/config.json'


Type Name Description
Array|String paths one or more paths to search for an appropriate config file

loadEnvironment (definition)

Map environment variables (if set) to keys in the config. Unset variables are ignored.

var envTransform = confab.loadEnvironment({
  'NODE_ENV': 'environment',
  'PORT': 'port'


Type Name Description
Object map a list of environment variables to map to config keys
Object options a list of options.

assign (definition)

Merge an object with the existing config, replacing any existing keys with the assign-ed values.

var envTransform = confab.assign({
  port: '1492'


Type Name Description
Object obj an object to merge into the config
Object obj2... additional objects to merge into the config

required (definition)

List required config fields and throw a ReferenceError with a list of any missing fields. If all fields are present, required acts as a pass-through.


Type Name Description
Array required the names of required fields in the config

defaults (definition)

Fill in any missing values in config with specified defaults

var defaultsTransform = confab.defaults({
  port: 3200,
  logLevel: 'debug'


Type Name Description
Object defaults default values to fill into the config
Boolean warn (Optional) print warning to `stdout` when a default value is being used

freeze (definition)

Freeze the config (hint: run this transformation last!)