mako

A pluggable build tool built around dependency trees.

What is this?

This is a build framework that specializes in working with projects that have complex dependency trees. It is highly configurable and relies on plugins to determine how the build runs.

This means it can be used in a wide variety of use-cases, such as building a front-end project (similar to Browserify and webpack), or a static site (similar to metalsmith). The plugin system is both robust and flexible, opening up many possibilities.

Check out the the wiki for resources on getting started.

How does it work?

The main flow for a mako build goes through 2 distinct phases: parse and compile.

The parse phase reads files from some source, (typically the local filesystem) identifies dependencies, then kicks off parse recursively as new files are discovered. Throughout this process, a dependency tree is being generated.

The compile phase takes the dependency tree generated by parse, and prepares to write the output files. (typically, also the local filesystem) During this phase, the tree could be deconstructed somewhat, such as when a tree of dependencies is combined into a single output file.

Throughout both of these phases are steps called hooks, which are configured by plugins. Check out the wiki for more resources about mako's internals.

About plugins

Plugins are absolutely necessary for mako to be useful. It was important for this tool to be flexible, so much inspiration was taken from Metalsmith.

Usage

The easiest way to get up and running with mako is to use the CLI. For web-based projets, there is also a lightweight development server. For advanced users, this module defines the public API:

var mako = require('mako');
var browser = require('mako-browser');

mako()                      // create a new runner
  .use(browser())           // add plugins (this is a bundle of plugins)
  .build('./index.js')      // run a build for index.js (assumed to be in pwd)
  .then(function (build) {  // this is a promise-based API
    // done
  });

API

mako([options])

Returns a new Runner instance, no need for the new keyword.

Available options:

• root the project root (default: pwd)
• plugins a list of plugins to add during init
• tree a predefined tree (eg: loading from mako-cache)
• concurrency used internally to set parallel concurrency limits

mako.Runner

The Runner class is exposed publicly to allow for advanced extensions.

runner.use(...plugins) (chainable)

Adds a new plugin to the runner. Each plugin is a Function, so any nested arrays will be flattened, allowing you to nest freely. (particularly useful for bundles)

runner.build(...entries)

The primary public interface, which runs both parse and compile for the given entries. It returns a Promise that resolves with a Build object that contains some information about the build itself.

runner.parse(...entries)

Runs parse for the passed entries. This method isn't typically used directly, but it can be useful for priming the tree for doing watches or inspecting the dependency tree.

It returns a Promise that resolves with a Build object.

runner.compile(...entries)

Runs compile for the given entries, this will skip the parse phase in case you know it has already been finished. (such as when calling runner.parse() manually)

It returns a Promise that resolves with a Build object.

runner.{hook}(extensions, handler)

Registers a handler for a specific hook, see the wiki for more information. There is a different method for each of the available hooks.

Build

This object is returned from each call to build/parse/compile, and it is shared by plugins throughout the build for holding the current tree, tracking timing and interacting with the core runner.

Described below is the public API primarily for end-users, but it is not exposed publicly at this time. Plugin authors should refer to the wiki for more information about plugin-specific APIs.

build.entries

This is an array of the entry files that were triggered for this build.

build.tree

This is a reference to the tree in use during the current phase.

If returned from runner.parse(), it will be a reference to runner.tree, so don't modify this tree unless you know exactly what you're doing.

If returned from either runner.compile() or runner.build(), this will be the same tree used during the compile phase. This tree is safe to modify, but it won't do anything, since the build is already complete.

build.runner

A reference to the runner that initiated this build.