@fulminate/config-builder

Fulminate Config Builder

A simple way to share the code that uses sensitive data like API keys, tokens, secret keys, etc. without losing code consistency. Heavily inspired by Symfony's parameters.yml usage logic.

Installation

Important! You want to install this package only after initializing package.json!

npm i --save @fulminate/config-builder

After NPM successfully downloads the package, the script will launch automatically.

It will ask you to provide:

• the destination directory where you would like to store your config file. Defaults to /.
• the name of the config file you want to create. Defaults to config.
• the format you would like to use for your config file. Currently supported types are JSON and YAML.

Assuming you've accepted all the default parameters, the config builder creates a config.dist.json file in the root directory of your project.

It will also add a fill-config script to your package.json which is a shortcut to start populating your config files.

NOTE

If you want to have more than one config file, feel free to run:

node ./node_modules/@fulminate/config-builder/index.js

and provide the -i flag to run the initializer script again and generate a new file for you. Bear in mind that currently creating new script will override the command created in your package.json so you will have to manually type it again. This issue will be fixed in future releases.

Update @2.1.0: Now creation script will write three commands to your package.json:

• fill-config - default script that checks if real config file does not exist and prompts user for answers based on dist file.
• fill-config-default - default script that checks if real config does not exist and writes all the default values to it based on dist file.
• fill-config-override - forced script that will override real config file if it exists and prompt for answers based on dist file.

This logic is a temporary measure and will be removed in upcoming releases.

Usage

After installation process is complete, populate the *.dist.* file with required data and run npm run fill-config. E.g.:

# You can use straight-forward key value pairs here
domain: 'example.com'

# You can nest objects
database:
  type: 'mysql'
  name: 'database'
  host: 'localhost'
  port: 3306
  username: 'root'
  password: 'root'
  
# You can use arrays. In this case the prompter will render
# a list of choices given in the array instead of an input
slackChannel:
  - 'general'
  - 'api-errors'
  - 'client-errors'

The same logic can be applied to dist files of JSON type:

{
  "domain": "example.com",
  "database": {
    "type": "mysql",
    "name": "database",
    "host": "localhost",
    "port": 3306,
    "username": "root",
    "password": "root"
  },
  "slackChannel": [
    "general",
    "api-errors",
    "client-errors"
  ]
}

Dist file explanation

The script will iterate over each line of dist file and prompt questions for real data you want to use. Each key will be used as both the question and the key in the final config file, whereas the value will be a default input value or a list of choices (in case the value is an array).

Real config file explanation

The value in the final config file will be either user input or the default value (the value of the *.dist.* file or the first item of the value if it is an array).

Using config builder with multiple dist files

If you have more than one dist file, you are free to launch the script directly:

node ./node_modules/@fulminate/config-builder/index.js -p --file=./PATH/FILENAME.dist.{json|yml}

Argument explanation

• -p runs the real config file population. Runs in junction with the --file flag to specify which dist file should be used. NOTE: this script creates the config file in the same directory and with the same extension as the dist file (e.g. having ./cfg/main.dist.yml the script will create ./cfg/main.yml config file).
• -i runs the prompter for creating a new dist file.
• --file=? is used to specify what is the dist file and where it is. E.g.: --file=./cfg/main.yml.
• --freshRun is a system flag that is required for the postinstall hook. DO NOT USE IT.
• --y works for populating and creating files. In both cases it applies default values and doesn't prompt user for input.
• --noComments is used in junction with -i and sets dist file being created to not have comments.
• --force makes Config Builder to override existing files. Works both for creating and populating scripts files.

Using configuration data in code

Just define an object in your code and parse the contents of the config file into it. Example with Node.js:

JSON:

{
  "server": {
    "port": 3000
  }
}

var fs = require('fs');
var app = require('express');

if (!fs.existsSync('./cfg/main.json')) {
   process.stdout.write('Config file not found');
   process.exit(1);
}

var cfg = JSON.parse(fs.readFileSync('./cfg/main.json'));

app.listen(cfg.server.port);

YAML:

server:
  port: 3000

var fs = require('fs');
var app = require('express');
var YAML = require('yamljs');

if (!fs.existsSync('./cfg/main.yml')) {
   process.stdout.write('Config file not found');
   process.exit(1);
}

var cfg = YAML.parse(fs.readFileSync('./cfg/main.yml'));

app.listen(cfg.server.port);

FYI

In case you decide to use YAML, you will need to install additional package to parse YAML to JS. In this package I used yamljs but it is totally up to you to pick the one you like.

Alternatively, you can take yamljs from @fulminate\config-builder\vendor.

TODO

• Unit testing
• Adding real config file to .*ignore
• Adding new script references to package.json upon creating more than one dist file (instead of overriding the same script)
• Prompting for amount of spaces used in dist files and config files (for the sake of consistent code style)
• Adding ability to provide human-readable questions alongside the key values in dist file
• Populating only those items that do not exist on real configuration file.