mako-config/README.md

# mako-config

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

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

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" } ]
  ]
}
```

### 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

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

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