rucola

rucola is a unix-style runtime configuration loader for Node.js apps that allows you to configure your application using configuration files in JSON, INI and YAML format, command-line arguments, and environment variables.
It's heavily inspired by the amazing rc module but it does things differently.

Sample Usage

Absolute Minimal Setup

You don't need more than this to add runtime configuration with command-line flags, environment variables and config files in INI, YAML and JSON to your app.

import rucola from 'rucola';
 
const conf = rucola('myapp');
conf.get('myvalue');

Slightly More Comprehensive Setup

The only argument required is appname. But in this example we're also providing default values and defining some aliases.

// Import the module
import rucola from 'rucola';
 
// The name of your app. It should be a string with no spaces and
// special characters. Kind of like an npm module name.
const appname = 'myapp';
 
// An object containing your default values. Make sure you cover
// everything essential to your app.
const defaults = {
  connection: {
    port: 1337,
    host: '127.0.0.1',
  },
};
 
// An object mapping aliases to config properties. Use the dot-notation
// to define aliases for nested properties.
const aliases = {
  p: 'connection.port',
  h: 'connection.host',
  r: 'color.red',
  R: 'recursive',
  v: 'version',
};
 
// Load the configuration.
const conf = rucola(appname, defaults, aliases);
 
// use conf.get() to read config variables 
// without throwing TypeErrors.
conf.get('connection.port')
// 1337
 
conf.connection.port;
// 1337
 
conf.get('i.dont.exist');
// undefined
 
conf.i.dont.exist
// TypeError: Cannot read property 'dont' of undefined

Documentation

API

conf = rucola(appname [, defaults [, aliases]])

Loads your configuration from all sources and returns an object containing all values.

import rucola from 'rucola';
const conf = rucola('myapp', defaults, aliases);

appname

The appname is your application's name. It will be used as a prefix for environment variables and in the name of your configuration files. It should be lower-cased without any spaces and other special characters. Kind of like you would name a module on npm.

defaults

The default values for your configuration. You don't have to cover every possible value but you should provide default values for all essential settings so your app can run without a configuration file.

The defaults can be either an object, or a string in any of the supported formats.

Using an object:

import rucola from 'rucola';
 
const defaults = {
  connection: {
    host: 'localhost',
    port: 8080,
  },
};
 
const conf = rucola('myapp', defaults);

Reading the defaults as a string from an INI file:

import path from 'path';
import fs from 'fs';
import rucola from 'rucola';
 
// Load defaults from an external file in any supported format.
const defaults = fs.readFileSync(path.join(__dirname, 'defaults.ini'), 'utf-8');
 
const conf = rucola('myapp', defaults);

aliases

An object to define short aliases (like -R for --recursive or -u for --user) for command-line arguments. If you want to define an alias for a nested property use the dot-notation.

import rucola from 'rucola';
 
const defaults = {
  connection: {
    host: 'localhost',
    port: 8080,
  },
};
 
const aliases = {
  h: 'connection.host',
  p: 'connection.port',
  v: 'version',
  V: 'verbose',
};
 
const conf = rucola('myapp', defaults, aliases);

Now you can use them as command-line arguments:

$ myapp -h 127.0.0.1 -p 8000 -V

which is the same as:

$ myapp --connection-host 127.0.0.1 --connection-port 8000 --verbose

value = conf.get(key)

conf.get() is a method to safely read config values of nested objects without throwing TypeErrors. You can use the dot-notation to access nested properties.

import rucola from 'rucola';
 
const defaults = {
  connection: {
    host: 'localhost',
    port: 8080,
  },
};
 
const conf = rucola('myapp', defaults);
 
conf.get('connection.host');
// 'localhost'
 
conf.get('server.hostname');
// undefined

Accessing conf.server.hostname directly would throw a TypeError because conf.server is undefined.

arr = conf.checkedConfigs

The conf.checkedConfigs property is an array containing all file paths that have been checked.

import rucola from 'rucola';
 
const conf = rucola('myapp');
console.log(conf.checkedConfigs);
 
// [ '/etc/myapp/config',
//   '/etc/myapprc',
//   '/etc/xdg/myapp/myapp.rc',
//   '/home/user/.config/myapp/config',
//   '/home/user/.config/myapp',
//   '/home/user/.myapp/config',
//   '/home/user/.myapprc' ]

arr = conf.usedConfigs

The conf.usedConfigs property is an array containing all file paths from which values have been loaded from.

import rucola from 'rucola';
 
const conf = rucola('myapp');
console.log(conf.usedConfigs);
 
// [ '/etc/myapprc', '/home/user/.config/myapp' ]

Normalization

All configuration options are normalized into a nested object structure with lower-case keys. Regardless of file format, environment variable, or command-line argument.

The following all translate into the following object:

{
  server: {
    connection: {
      host: "localhost",
      port: "9000"
    }
  }
}

Environment Variables

MYAPP_SERVER_CONNECTION_HOST=localhost \
MYAPP_SERVER_CONNECTION_PORT=9000 \
myapp

MYAPP_sErVeR_CoNNEcTION_hOsT=localhost \
MYAPP_SerVer_coNneCtiOn_PorT=9000 \
myapp

Command-Line Arguments

myapp --server-connection-host localhost \
      --server-connection-port 9000

myapp --sERvER-COnNEcTIoN-hOSt localhost \
      --SErVEr-CoNNeCtIOn-pOrt 9000

Config Files

JSON:

{
  "server": {
    "connection": {
      "host": "localhost",
      "port": "9000"
    }
  }
}

{
  "Server.Connection": {
    "Host": "localhost",
    "Port": "9000"
  }
}

{
  "SERVER.Connection.host": "localhost",
  "SERVER.Connection.port": "9000"
}

INI:

[server]
connection.host = localhost
connection.port = 9000

[Server.Connection]
host = localhost
port = 9000

SERVER.connection.host = localhost
SERVER.connection.port = 9000

YAML:

server:
  connection:
    host: localhost
    port: 9000

Server.Connection:
  Host: localhost
  Port: 9000

SERVER.Connection.Host: localhost
SERVER.Connection.Port: 9000

Configuration Sources

Given your application name is "myapp", rucola will load configuration values from the following sources in this paricular order from bottom to top, and merge the values in the same order.

• command-line arguments
• environment variables
• if you passed an option --config file then from that file
• a local .myapprc or the first found looking in ./ ../ ../../ ../../../ etc
• $HOME/.myapprc
• $HOME/.myapp/config
• $HOME/.config/myapp
• $HOME/.config/myapp/config
• /etc/xdg/myapp/myapp.rc (unix-style only)
• /etc/myapprc (unix-style only)
• /etc/myapp/config (unix-style only)
• defaults

File Formats

rucola supports JSON (with comments), INI and YAML, and auto-detects the format.

Example INI file:

; this is a comment 
 
yolo = true
 
[connection]
port = 1337
host = 127.0.0.1
 
; nested sections 
 
[nice.foods]
green = broccoli
orange = carrots
 
[nice.colors]
emerald = true
turquoise = false

Same example in JSON:

// this is a comment
 
{
  "yolo": true,
  "connection": {
    "port": "1337",
    "host": "127.0.0.1"
  },
 
// nested sections
 
  "nice": {
    "foods": {
      "green": "broccoli",
      "orange": "carrots"
    },
    "colors": {
      "emerald": true,
      "turquoise": false
    }
  }
}

Same example in YAML:

---
# this is a comment 
 
yolo: true
 
connection:
  port: 1337
  host: 127.0.0.1
 
# nested sections 
 
nice.foods:
  green: broccoli
  orange: carrots
 
nice.colors:
  emerald: true
  turquoise: false

Environment Variables

Environment variables need to be prefixed with the application name and are upper case. Keep in mind that environment variables always have string values. So you may have to type cast the values into whetever you need.

MYAPP_CONNECTION_PORT=1337 YOLO=true myapp

becomes:

{
  connection: {
    port: "1337"
  },
  yolo: "true",
}

Command-line Arguments

myapp --connection-port 1337 --yolo

becomes:

{
  connection: {
    port: 1337
  },
  yolo: true
}

Difference Between rucola And rc

The big difference between rucola and rc is that rucola normalizes everything so you can use environment variables and command-line arguments in a way a user would expect to use them.

If your app name is "myapp" and you wanted the following config object,

{
  connection: {
    host: "localhost",
    port: 9000
  }
}

in rc you would have to use environment variables like this (with double unserscores for nested properties):

myapp_connection__host=localhost \
myapp_connection__port=9000 \
myapp

and command-line arguments like this:

myapp --connection.host localhost --connection.port 9000

which is not what you'd expect in a unix-like environment.

With rucola you can use environment variables like this:

MYAPP_CONNECTION_HOST=localhost \
MYAPP_CONNECTION_PORT=9000 \
myapp

and command-line arguments like this:

myapp --connection-host localhost --connection-port 9000

which is much closer to what a user might expect.

Things that rucola can and rc can't:

• Nice command-line arguments and environment variables
• Provides .get() function to access values without throwing TypeErrors
• Provide a list of files from which values were read from
• Support for aliases
• Support YAML format

Things that rc can and rucola can't:

• Swap out minimist for a different option parser

License

Copyright (c) 2015 - 2018 Max Kueng and contributors

MIT License