mako-config/README.md

# mako-config

> A helper for loading [mako][mako] build config from a file.

[![npm version][npm-badge]][npm]
[![build status][travis-badge]][travis]
[![coverage][coveralls-badge]][coveralls]
[![npm dependencies][david-badge]][david]
[![npm dev dependencies][david-dev-badge]][david-dev]
[![code style][standard-badge]][standard]

This helper encapsulates the logic for loading a mako build configuration file,
allowing easier use amongst different tools.

## Usage

This module is a simple function loads and normalizes mako configuration files:

```js
var load = require('mako-config');

load('/path/to/file.json').then(function (config) {
  // config.entries
  // config.plugins
});
```

## Configuration File Structure

### root

If specified, this allows you to set a custom root/base path for you `entries`.

**NOTE:** paths are still resolved relative to the config file location, but
when these files are added to the mako tree, their base path will be this
custom value.

### entries

This will be an array of glob patterns that will be resolved to form a single
list of entry files. The patterns will all be resolved relative to the config
file's location.

```json
{
  "entries": [
    "index.{js,css}",
    "pages/**/index.{js,css}",
    "public/**"
  ]
}
```

### plugins

This will be an array of plugins to load, they can either be installed modules
or point to local modules of your own:

```json
{
  "plugins": [
    "mako-browser",
    "./local-plugin.js"
  ]
}
```

By default, no arguments will be passed during initialization. To change this,
use an array:

```json
{
  "plugins": [
    [ "mako-browser", { "output": "dist" } ]
  ]
}
```

### concurrency

If you want to set the concurrency level, you can use this property as a number.

### env

When you want to load plugins or entries only in a specific `NODE_ENV`, you can
create an object here for each of those environments. (the default env is
"development")

In this example, we add JS and CSS minification (via uglify and cleancss
respectively) when we run with `NODE_ENV=production`:

```json
{
  "env": {
    "production": {
      "plugins": [
        "mako-uglify",
        "mako-cleancss"
      ]
    }
  }
}
```

The structure underneath each env is identical to the root level, and both
`entries` and `plugins` will be appended to those defined at the root.

## API

### load(file, [overrides])

This function accepts `file` as an absolute path to the configuration file. The
`overrides` is a list of entries that will override the ones specified in the
config file.

It returns a promise that resolves with an object. It will contain the following
keys:

 - `root`: the absolute path to an alternate root (`null` if not specified)
 - `entries`: an array of absolute file paths to all the matched entry files
 - `plugins`: an array of the initialized plugin functions
 - `concurrency`: a number for concurrency if included in the config file
 - `path`: the absolute path to the file that was loaded (aka: `file`)
 - `original`: a copy of the original JSON structure

### load.sync(file, [overrides])

The same arguments are accepted, and the same result is returned synchronously.


[mako]: https://github.com/makojs/core
[coveralls]: https://coveralls.io/github/makojs/config
[coveralls-badge]: https://img.shields.io/coveralls/makojs/config.svg
[david]: https://david-dm.org/makojs/config
[david-badge]: https://img.shields.io/david/makojs/config.svg
[david-dev]: https://david-dm.org/makojs/config#info=devDependencies
[david-dev-badge]: https://img.shields.io/david/dev/makojs/config.svg
[npm]: https://www.npmjs.com/package/mako-config
[npm-badge]: https://img.shields.io/npm/v/mako-config.svg
[standard]: http://standardjs.com/
[standard-badge]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg
[travis]: https://travis-ci.org/makojs/config
[travis-badge]: https://img.shields.io/travis/makojs/config.svg