littleconf

LittleConf

LittleConf is a simple library for loading project configuration files.

import { getConfig } from 'littleconf';
const config = await getConfig();

This will load a YAML configuration file named <PackageName>.conf or <PackageName>.conf.js from the package root directory. By default, the package name is discovered from the project's package.json file.

Config Defaults

LittleConf will also look for a file named <PackageName>-defaults.conf or <PackageName>-defaults.conf.js in the package root directory. This file is merged with the main config file and can supply defaults. By convention, the defaults file should be committed to the source repository, and the main config file should not.

Config Filename and Search Path

LittleConf looks for the main config file under the following namess. It uses the first one that applies:

• The value of the filenameOverride option.
• The value of the -c command-line argument.
• The value of the environment variable PACKAGE_NAME_CONFIG.
• The value of the filename option.
• package-name.conf

If the above does not yield an absolute path, LittleConf first looks for the file in the package root directory, then in /etc.

Environments

In the config file, you can specify a set of configuration values that are only applied when a given "environment" is configured. The config file with environments looks like this:

foo: "banana"
bar: 12
environments:
	local:
		foo: "apple"
	prod:
		foo: "pear"

The envionment is normally selected using the NODE_ENV or PROJECT_NAME_ENV environment variable, but can also be selected using the following methods (the first that exists is used):

• The environmentOverride option.
• The --config-env command-line argument.
• The PROJECT_NAME_ENV environment variable.
• The NODE_ENV environment variable.
• The defaultEnvironment option.
• The default environment of "local"

Including Other Config Files

A config value named _include can be used to load another config file and merge its contents in at that point. Any sibling keys at the same level take precedence over (ie, override) the included file's values:

# main.conf
foo: "banana"
database:
  _include: "database.conf"
  poolSize: 5

# database.conf
host: "localhost"
poolSize: 10

This results in:

foo: "banana"
database:
  host: "localhost"
  poolSize: 5

_include can appear anywhere in the config tree, including at the root of a file or inside an environments block, in which case the included file is merged in at that same level:

environments:
  prod:
    _include: "prod.conf"

Included files are themselves treated as full config files: if an included file has its own environments key, only the section matching the currently-active environment is merged in, and any _include directives it contains are resolved as well. A relative _include path is resolved relative to the directory of the file it appears in (not the project root), so included files can themselves include further files using paths relative to their own location. Absolute paths are used as-is.

Referencing Other Values

A config value can be set to reference another value elsewhere in the config using _ref, given as a dot-separated path resolved from the root of the fully-merged config:

myObject:
  myFirstValue: "foo"
mySecondValue:
  _ref: "myObject.myFirstValue"

This results in mySecondValue being set to "foo".

A _ref can also point into a different config file entirely by additionally specifying _file, in which case the path is resolved against the root of that file instead of the current config:

mySecondValue:
  _ref: "someValue"
  _file: "other.conf"

As with _include, a relative _file path is resolved relative to the directory of the file the _ref appears in (not the project root); absolute paths are used as-is.

Command-line Arguments

To allow LittleConf to handle command-line arguments, it needs to be supplied with the argv option. This can come from a standard argument parsing package like optimist or yargs.

const argv = require('yargs').argv;
const config = require('littleconf').getConfig({ argv: argv });

Individual Setting Overrides

Individual settings can be overridden using command-line arguments or environment variables. Environment variables are named PROJECT_NAME_CONFIG_SETTINGNAME and command-line arguments look like --config-setting-SETTINGNAME.

Options

These options can be supplied in the argument to getConfig().

• argv - The set of command-line arguments.
• projectName - The name of the project. Defaults to the name property in package.json.
• environmentOverride - Force a specific config environment value.
• cliArgumentEnvironment - The name of the CLI argument to use for selecting the config environment. Defaults to "config-env".
• rootDir - The root directory of the project. By default this is determined by using require.main and traversing upwards until a package.json is found.
• envVariableEnvironment - Selects a specific name for the environment variable to determine the config environment rather than the default of PROJECT_NAME_ENV.
• defaultEnvironment - Sets the default config environment. Defaults to "local".
• defaultsFilename - Sets the filename to use for the defaults file. Normally "projectname-defaults.conf".
• filenameOverride - Forces the name/path of the main config file.
• filename - Default name of the main config file. Defaults to "projectname.conf".
• cliArgumentFile - Name of the command-line argument to specify the config file. Defaults to "c".
• envVariableFile - Name of the environment variable to specify the config file. Defaults to PROJECT_NAME_CONFIG.