npm package: @fulminate/config-builder
Description: Manage your project parameters and sensitive data (e.g. API keys or secket tokens) easily and conveniently.
Author: Sergey Orlov
Latest version: 2.1.0

# Fulminate Config Builder
[![Build Status](https://travis-ci.org/fulminate-js/config-builder.svg?branch=master)](https://travis-ci.org/fulminate-js/config-builder)
[![MIT Licence](https://badges.frapsoft.com/os/mit/mit.png?v=103)](https://opensource.org/licenses/mit-license.php)
[![Join the chat at https://gitter.im/jstriebel/badges](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/fulminate-js/Lobby)

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.

![Prompt for user input](https://raw.githubusercontent.com/fulminate-js/config-builder/master/doc/fresh_run_script.png)

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.:

```yaml
# 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:

```json
{
  "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:

```json
{
  "server": {
    "port": 3000
  }
}
```

```js
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:

```yaml
server:
  port: 3000
```

```js
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.