autoconfig v1.0.0-rc.1

autoconfig

Overview

An npm module to simplify configuration in a Node.js environment using a configuration file. Much of this library was based on mkleehammer/autoconfig a Python configuration module using a config file. The biggest difference between the Python and Node.js versions is that Node.js version excepts an object instead of parameters. Node.js does not support default paramters without the use of harmony flags::

  var autoconfig = require('autoconfig');
  autoconfig.init();

With these simple lines before other imports, you can add variables to process.env which provides global access to the configuration.

After using Python autoconfig and needing a configuration thats as easy for Node.js, I decided to create this project for all of my Node.js projects.

(From mkleehammer/autoconfig) - the 12 Factor App recommends keeping configuration in environment variables...

A common solution, that can lead to problems, is to set environment variables or command line options to the currently running user's environment. The first problem is Windows vs macOS/Linux style of setting the environment varable SET NODE_ENV=development (or setx) vs export NODE_ENV=development. The other option is to set it directly in the run node command, but that is sometimes more confusing on Windows vs macOS/Linux SET NODE_ENV=development && node index.js vs NODE_ENV=development node index.js.

In the end, this usually ends up to using a config file on the computer or hard-coded (env = process.env.NODE_ENV ? process.env.NODE_ENV : 'development') that is checked-in with some sort of .dev .qa .prod in the filename and could easily be error prone. The computer "usually" never changes environments mid-development cycle so it makes sense to have a configruation that is loaded to the process.env taken from a file specific to this machine. Given the file's location, it can be machine-wide (think QA only server with multiple projects) or project specific, see below.

Simple Example

If an object is not passed, the library searches for a file named .config.json, starting from the current directory (process.cwd()) and searching upwards.

Using well-known JSON format, this makes it easy to get started instantly

  {
    "env": {
      "NODE_ENV": "development",
      "DATABASE_URL": "postgresql://localhost/test?client_encoding=utf8"
    },
    "other": {
      "DATABASE_URL": "postgresql://otherhose/test?client_encoding=utf8"
    }
  }

The two entries NODE_ENV and DATABASE_URL are added to process.env and are accessible anywhere in any Node.js file by simply by using process.env.NODE_ENV OR process.env.DATABASE_URL.

Environment Variables

If an "env" section exists, its items are always copied, but additional sections can be copied also by passing them via the env keyword. The value can be a section name or a list of section names - the object can contain env (environment name), filename, searchfrom (filepath or null to search upward)

autoconfig.init({env: 'other'});             # copy from env and other
autoconfig.init({env: ['other', 'another]}); # copy from env, other, and another

Even though env is always copied to process.env, other environments (if passed in) override env. This means that in the "Simple Example" above, other's "DATABASE_URL" will be used when using "process.env.DATABASE_URL" even though env contains the same configuration.

Locating The Config File

The default behavior is to look for a file named ".config.json", starting in the current working directory and searching upwards. If a file is not found, an exception is thrown.

The init function accepts two keywords to customize this:

filename Pass just a filename, such as "project.ini" to search for a different filename.

Pass an absolute path name, such as "/etc/project.ini", to disable searching and use the filename as given.

searchfrom An optional directory to begin the search from. If not provided, the default is the current working directory as provided by process.cwd().

To simplify configuration, a path to a file can also be passed and the search will begin in the same directory as the file. This is particularly handy for starting a search from the directory where the calling module is located

autoconfig.init({
    env: 'env',
    searchfrom: __dirname
});

This object value is ignored if filename is an absolute path since no search is performed.