transfigure

Transform/transpile higher order file contents to js|css|html

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.

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

css

html

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)

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: [
    'foo',
    'bar'
  ]
};

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

exports.compile = function (contentoptionsfn) {
  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)