Skip to content
This repository has been archived by the owner. It is now read-only.
Painless configuration with defaults file, environment variables, arguments, function parameters.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Painless configuration for Node apps with defaults file, environment variables, arguments, function parameters.

defaults file < process.env < command line arguments < function call override

Status: No Longer Maintained

This repo is no longer actively maintained.

Getting started

Create your config object:

var qconf = require('qconf.js'),
  config = qconf(); // 99% of the time, this is all you need!

Extra credit

Create a JSON file: ./config/config.json

  "default_setting": true,
  "envOverride": false,
  "arg_override": false,
  "param_override": false

Maybe source some environment variables:

export env_override=true

Try a command-line option:

node myfile.js --arg-option true


Painless configuration for your apps!


Got sick of the complexity of nconf. Don't try to be everything to everybody. Just get a simple job done with simple code.



This is the function that gets imported when you require qconf.

Creates a configuration object for your app by reading configuration settings from a defaults file, environment variables, command line arguments, and finally a function parameters hash, in reverse priority.

  • @param {Object} [overrides] A map of config keys and values.
  • @param {Array} || {String} [filesURI] An array of config files in order of precedence (least to most) or path to the defaults file. Can be the only parameter.
  • @return {Object} config A configuration object.
  • @return {Function} config.get The get method.
  • @return {Function} config.set The set method.

More examples using overrides. File overrides support JSON and YAML files:

var qconf = require('qconf'),
  // You can pass in an array of configuration files.
  // Last in wins:
  config = qconf(['file://config/defaults.json', 'file://config/overrides.yml']);
var qconf = require('qconf'),
  // You can pass in argument overrides and file overrides.
  // Argument overrides win.
  config = qconf({override: 'This setting trumps all.'},
    ['file://config/defaults.json', 'file://config/overrides.yml']);

The config object

The config object is the object returned when you call qconf(). This is the getter and setter for all your app's environment variables.


Return the value of the attribute requested.

  • @param {String} attr The name of the attribute to return.
  • @return {Any} The value of the requested attribute.


Set the value of an attribute.

  • @param {String} attr The name of the attribute to set.
  • @param {Any} value The value to set the attribute to.
  • @return {Object} The config object (for chaining).


The config object is an event emitter.


config.get() will emit the event 'undefined' if the value of the variable in question is undefined. It will also emit a convenient, searchable message that you can log and easily find in your logs:

'WARNING: Undefined environment variable: ' + `attr`

attr refers to the name of the variable you tried to get.

For example:

var qconf = require('qconf'),
  config = qconf(),
  util = require('util');
config.on('undefined', function (msg, attr) {
  // or build a custom message:
  util.log('WAT? Can\'t find ' + attr);
// Logs:
// "WARNING: Undefined environment variable: some_var"
// "WAT? Can't find some_var"
You can’t perform that action at this time.