configg

A Node configuration manager

"configg" organizes hierarchical configurations for your App deployments while keeping the different configurations for your App and its modules isolated.

Starting from a defined set of default parameters, your App gets extended for its different deployment environments (development, staging, production, ...), optional the hosts it's going to run and/or the instance it uses.

The different environments get controlled using different environment variables (e.g. NODE_ENV for deployment).

To provide a clean separation between code and config as proclaimed by The Twelve-Factor App each App or module can get its own configuration for the different deployment environments.

Configurations are stored in configuration files inside the /config folder which resides next to a package.json file. Isolation (i.e. a module or App can only access its associated configuration) is maintained by extracting name and version from the package.json file. This allows extending/ overwriting values for modules from your App-config or even a module which includes other sub-modules.

Extensible with plugins... Check npm for keyword configg-plugin.

This project is inspired from node-config.

Table of Contents

• Quick Start
  • Use module overrides
• Plugins
• Documentation
• Contribution and License Agreement
• License

Quick Start

The following examples use Hjson but other file formats including Js, JSON are supported.

All examples can be found in the examples folder. Run run.sh to see things in action.

Install configg in your App directory

$ npm install configg
$ mkdir config

Define default values for your App

/* ./config/default.hjson */
{
  config: { // < always start with a config object...
    backend: {
      // configuration values of your app/ module go in here
      host: "test-system",
      port: 8080,
      timeout: 3600
    }
  }
}

Define production overrides

/* ./config/production.hjson */
{
  config: {
    backend: {
      host: "production-system",
      path: "/path-on-prod"
    }
  }
}

Add to your code

/* ./index.js */
var config = require('configg')()
console.log(config.get('config.backend'))

Running on development:

$ node index.js
{ host: 'test-system', port: 8080, timeout: 3600 }

Running on production:

$ export NODE_ENV=production
$ node index.js
{ host: 'production-system', port: 8080, timeout: 3600, path: '/path-on-prod' }

Use module overrides

Assuming you now want to add a database connection to your Application using a "my-database" module.

In development you'd like to use the default settings provided within "my-database" but change the host and credentials.

All examples can be found in the examples folder. Run run-database.sh to see things in action.

/* /node_modules/my-database/config/default.js */
module.exports = {
  config: {
    host: 'test-db',
    port: 1529,
    credentials: {
      user: 'test',
      pass: '1234'
    }
  },
  common: {
    pool: false
  }
}

Our sample database module

/* database.js */
var config = require('configg')()

console.log('---- Module "my-database" ----')
console.log(config.get('config'))

module.exports = {}

Application with module "my-database"

/* ./index-database.js */
var config = require('configg')()
var database = require('my-database')

console.log('---- Application ----')
console.log(config.get('config.backend'))

Running the App in development:

$ NODE_ENV="" node index-database.js
---- Module "my-database" ----
{ host: 'test-db',
  port: 1529,
  credentials: { user: 'test', pass: '1234' } }
---- Application ----
{ host: 'test-system', port: 8080, timeout: 3600 }

For you productions settings you like to change to a different user and password using "my-database" as a module. In your Application configuration add a branch named after the "my-database" module:

/* ./config/production.hjson */
{
  config: { //< The config for the current module
    backend: {
      host: "production-system",
      path: "/path-on-prod"
    }
  },
  "my-database": {  //< Needs to be the name of the module!
    host: "production-db",
    credentials: {
      user: 'admin',
      pass: 'always-on-the-1'
    }
  },
  common: {
    pool: true
  }
}

Runnning in production mode:

$ node index-database.js --NODE_ENV=production
---- Module "my-database" ----
{ host: 'production-db', port: 1529,
  credentials: { user: 'admin', pass: 'always-on-the-1' } }
---- Application ----
{ host: 'production-system', port: 8080, timeout: 3600, path: '/path-on-prod' }

Plugins

Check npm for keyword configg-plugin.

To use plugins add a plugins array to the default or any config file.

module.exports = {
  config: {
    // ...
  },
  common: {
    // ...
  },
  plugins: [
    ['configg-plugin-vault-nacl']
  ]
}

If you like to write your own plugin check out docs/plugins.md.

Documentation

Further documentation is at docs/documentation.md.

Contribution and License Agreement

If you contribute code to this project, you are implicitly allowing your code to be distributed under the MIT license. You are also implicitly verifying that all code is your original work or correctly attributed with the source of its origin and license.

License

Copyright (c) commenthol (MIT License)

See LICENSE for more info.