Transfigure

Transfigure is a plug-in based transformer/transpiler for higher order languages that need to be converted to js|css|html. It provides the compile functionality for the Buddy build tool.

Plug-in transpilers

In order to add transpilation support to Buddy projects, separate transfigure- modules need to be installed alongside Buddy:

$ npm install transfigure-coffeescript transfigure-less

The following plug-ins are currently available (with version numbers tracking their underlying language versions):

js

• transfigure-babel
• transfigure-coffeescript
• transfigure-react [deprecated - JSX now compiled with transfigure-babel]

css

• transfigure-less
• transfigure-stylus

html

• transfigure-dust
• transfigure-handlebars
• transfigure-jade
• transfigure-nunjucks
• transfigure-twig

Writing your own plug-in

Writing a plug-in for Transfigure is relatively simple. Each plun-in should conform to the following requirements:

1. Must have a package name starting with transfigure-
2. Must implement the correct registration and compile behaviour
3. Must be installed in the current project's node_modules directory (or a reachable parent)

API

Modules must export a registration object with name and extensions properties (Note that a plug-in can register multiple extensions):

exports.registration = {
  name: 'myPlugin',
  extensions: {
    js: [
      'foo',
      'bar'
    ]
  }
};

Modules must export an async compile function with the following signature and behaviour:

exports.compile = function (content, options, fn) {
  try {
    content = myPlugin.api(content, options);
    fn(null, content);
  } catch (err) {
    // Attach current filepath for helpful console output
    err.filepath = options.filepath;
    fn(err);
  }
};

The passed options object has the following properties:

• filepath: the fully resolved file path (ex: /users/alex/projects/foo/src/js/foo.js)
• extension: the file extension (ex: js)
• name: the file name without extension (ex: foo)
• type: the build target type (js, css, or html)
• includes: an array of html include/partials objects that can be precompiled/loaded before compilation
  • id: a unique dependency id
  • content: the file content
• cache: an html template cache instance that may be used to store precompiled html templates (see transfigure-dust and transfigure-nunjucks for usage)