node package manager


Environment-aware configuration.


Lead Maintainer: Poornima Venkat

Simple, environment-based configuration. confit loads a default JSON configuration file, additionally loading environment-specific files, if applicable. It will also process the loaded files using any configured shortstop protocol handlers—see Options below.

confit adds support for adding JavaScript-style comments in your json files as each file is processed by shush before being merged into your config.

var confit = require('confit');
  • options (String | Object) - the base directory in which config files live or a configuration object. If no arguments is provided, defaults to the directory of the calling file. Signature function (err, config) {}
  • returns - config factory.
'use strict';
var path = require('path');
var confit = require('confit');
var basedir = path.join(__dirname, 'config');
confit(basedir).create(function (err, config) {
    config.get; // Function 
    config.set; // Function 
    config.use; // Function 
    config.get('env:env'); // 'development' 
  • addOverride(filepath) (or) addOverride(obj) - Use this to add file (.json or .js), to merge with the config datastore and override the overlapping data if any. Alternatively, you can also pass a json object to override.
  • addDefault(filepath) (or) addDefault(obj) - Use this to add default file (.json or .js), to merge with the config datastore and serve as the default datastore. Alternatively, you can also pass a json object for defaults.
  • create(callback) - Creates the config object, ready for use. Callback signature: function (err, config) {}
// All methods besides `create` are chainable 
    .addDefault('./mydefaults.json')  //or .addDefault({foo: 'bar'}) 
    .addOverride('./mysettings.json') //or .addOverride({foo: 'baz'}) 
    .create(function (err, config) {
        // ... 
// - or - 
// var factory = confit(options); 
// factory.addOverride('./mysettings.json'); 
// factory.create(function (err, config) { 
//     // ... 
// }); 
  • basedir (String) - the base directory in which config files can be found.
  • protocols (Object) - An object containing a mapping of shortstop protocols to handler implementations. This protocols will be used to process the config data prior to registration.
  • defaults (String) - the name of the file containing all default values. Defaults to config.json.
'use strict';
var path = require('path');
var confit = require('confit');
var handlers = require('shortstop-handlers');
var options = {
    basedir: path.join(__dirname, 'config');
    protocols: {
        file: handlers.file,
        glob: handlers.glob
confit(options).create(function (err, config) {
    // ... 
  • get(key) - Retrieve the value for a given key. Colon-delimited keys can be used to traverse the object hierarchy.
  • set(key, value) - Set a value for the given key. Colon-delimited keys can be used to traverse the object hierarchy.
  • use(obj) - merge provided object into config.
config.set('foo', 'bar');
config.get('foo'); // 'bar' 
config.use({ foo: 'baz' });
config.get('foo'); // 'baz' 
config.use({ a: { b: { c: 'd' } } } );
config.get('a:b:c'); // 'd' 

By default, confit loads process.env and argv values upon initialization. Additionally, it creates convenience environment properties prefixed with env: based on the current NODE_ENV setting, defaulting to development. It also normalizes NODE_ENV settings so values starting with prod become production, starting with stag become staging, starting with test become test and starting with dev become development.

// NODE_ENV='dev' 
config.get('NODE_ENV');        // 'dev' 
config.get('env:env');         // 'development' 
config.get('env:development'); // true 
config.get('env:test');        // false 
config.get('env:staging');     // false 
config.get('env:production');  // false 
// NODE_ENV='custom' 
config.get('NODE_ENV');        // 'custom' 
config.get('env:env');         // 'custom' 
config.get('env:development'); // false 
config.get('env:test');        // false 
config.get('env:staging');     // false 
config.get('env:production');  // false 
config.get('env:custom');      // true 

Precedence takes the following form (lower numbers overwrite higher numbers):

  1. command line arguments
  2. env variables
  3. environment-specific config (e.g., development.json)
  4. main config (config.json)
  5. env normalization (env, env:development, etc)

Confit by default comes with 2 shortstop handlers enabled.

  • import: Merges the contents of the specified file into configuration under a given key.
    "foo": "import:./myjsonfile"
  • config: Replaces with the value at a given key. Note that the keys in this case are dot (.) delimited.
    "foo": {
        "bar": true
    "foobar": ""