hardwired configuration loader


The non-configurable configuration loader for lazy people.

The only option is to pass rc the name of your app, and your default configuration.

var conf = require('rc')(appname, {
  //defaults go here. 
  port: 2468,
  //defaults which are objects will be merged, not replaced 
  views: {
    engine: 'jade'

rc will return your configuration options merged with the defaults you specify. If you pass in a predefined defaults object, it will be mutated:

var conf = {};
require('rc')(appname, conf);

If rc finds any config files for your app, the returned config object will have a configs array containing their paths:

var appCfg = require('rc')(appname, conf);
appCfg.configs[0] // /etc/appnamerc 
appCfg.configs[1] // /home/dominictarr/.config/appname 
appCfg.config // same as appCfg.configs[appCfg.configs.length - 1] 

Given your application name (appname), rc will look in all the obvious places for configuration.

  • command line arguments (parsed by minimist)
  • environment variables prefixed with ${appname}_
    • or use "__" to indicate nested properties
      (e.g. appname_foo__bar__baz => foo.bar.baz)
  • if you passed an option --config file then from that file
  • a local .${appname}rc or the first found looking in ./ ../ ../../ ../../../ etc.
  • $HOME/.${appname}rc
  • $HOME/.${appname}/config
  • $HOME/.config/${appname}
  • $HOME/.config/${appname}/config
  • /etc/${appname}rc
  • /etc/${appname}/config
  • the defaults object you passed in.

All configuration sources that were found will be flattened into one object, so that sources earlier in this list override later ones.

Configuration files (e.g. .appnamerc) may be in either json or ini format. The example configurations below are equivalent:

; You can include comments in `ini` format if you want.
; `rc` has built-in support for ini sections, see?
  www     = ./commands/www
  console = ./commands/repl
; You can even do nested sections
  engine  = ejs
  new     = generate-new
  engine  = generate-backend
  // You can even comment your JSON, if you want 
  "dependsOn": "0.10.0",
  "commands": {
    "www": "./commands/www",
    "console": "./commands/repl"
  "generators": {
    "options": {
      "engine": "ejs"
    "modules": {
      "new": "generate-new",
      "backend": "generate-backend"

Comments are stripped from JSON config via strip-json-comments.

Since ini, and env variables do not have a standard for types, your application needs be prepared for strings.

You may pass in your own argv as the third argument to rc. This is in case you want to use your own command-line opts parser.

require('rc')(appname, defaults, customArgvParser);

If you have a special need to use a non-standard parser, you can do so by passing in the parser as the 4th argument. (leave the 3rd as null to get the default args parser)

require('rc')(appname, defaults, null, parser);

This may also be used to force a more strict format, such as strict, valid JSON only.

rc is running fs.statSync-- so make sure you don't use it in a hot code path (e.g. a request handler)

Multi-licensed under the two-clause BSD License, MIT License, or Apache License, version 2.0