node package manager


Templating madness!


Build Status NPM version Coverage Status


$ npm install tarima

Tarima is a pre-processing tool based on filename extensions.

Of course there are alternatives or even would be easier to setup Gulp, Brunch, whatever... but repeating the same stuff every-time becomes frustrating.

Also we experienced serious issues from migrating from Grunt to Gulp, and then from Browserify to Webpack.

How it works

Lets say view.js.ract.jade will produce a pre-compiled template for Ractive, which is rendered from pug, etc.

If you omit the js extension then view.ract.jade will produce markup, since html is the default extension for the Ractive engine.

You can add as many extensions you want, whilst the output is valid input for the next renderer in the chain.


load(filename, options) — Shortcut for calling parse() from reading the given filename with fs.readFileSync().

See below. ↓

parse(filename, source, options) — Primary method for turning the given source into a abstract representation of itself.

The filename is required but not required to exists, is just a hint for tarima to understand what to do with it.

The resulting object will contain a render() callback and params object, respectively:

  • partial.render(locals, callback) — Performs the transpilation on the given source, producing a new source.

  • partial.params — An object like:

  "filename": "view.ract.pug",
  "options": {}, // passed options to the factory 
  "source": "<x>y</x>",
  "parts": ["ract", "pug"],
  "name": "view",
  "data": {}, // any data passed as front-matter 
  "deps": [], // all imported-or-required sources 
  "locals": {}, // values passed from the callback 
  "runtimes": [], // js-expressions for required modules 
  "extension": "html"


var tarima = require('tarima');
var view = tarima.parse('view.ract.pug', 'x {{"y"}}');
// direct 
view.render(function(err, result) {
  console.log(err, result);


bundle(partial, bundleOptions) — Performs the transpilation on the given source, and turn it into a new module.

  • Given multiple sources the resulting module will export an object with all transpiled sources, and all of them should be valid templates in order to work.

  • Some sources like stylesheets already performs some kind on bundling, but other sources like Javascript doesn't.


// bundled 
tarima.bundle(view, locals)
  .render(function(err, result) {
    console.log(err, result);


cwd — Save all file paths relative to this directory cache — Cache object being used by Rollup.js rollup — Configuration object used by Rollup.js exports — Can be cjs or es6. Prefix module.exports vs export default

Front Matter

All parsed files can use a front-matter block for local data.

  title: Untitled
  _render: other/layout.hbs
  extended: !include ../path/to.yml
h1= title + extended.some.value

Note you can merge additional files using the !include directive within any front-matter block.

Special keys

Tarima use some predefined keys in order to customize certain aspects of rendering, transpilation or bundling individually:

_render — Renders the actual source using other supported source as template, useful for reusing views.

The given template should be able to output the yield variable:

{{!-- other/layout.hbs --}}
<div>{{{ yield }}}</div>



The _render option is available only for templates.

_bundle — This value will be used as the moduleName option for rollup, as stated on its guide it's required for modules (or entry-points this way).

_format — This value is passed directly as format option for rollup, available formats are: amd, js, es6, iife, umd.

Both options _bundle and _format are available only when bundle() is called, see above.

Supported engines

You can install the following dependencies for specific support:

  • npm install vue-template-compiler.vue component files and templates
  • npm install and .litcoffee (aka
  • npm install sources (experimental)
  • npm install pug.pug and .jade (legacy)
  • npm install less.less
  • npm install imba.imba
  • npm install jisp.jisp
  • npm install ejs.ejs
  • npm install styl.styl
  • npm install handlebars.hbs
  • npm install ractive.ract and .rv
  • npm install, .mkd
  • npm install idom-template.idom
  • npm install babel-core@^5.jsx and .es6.js

Tarima doesn't ship any dependency for the supported engines, is your responsability to install whatever you will need.

ES6 support

Tarima supports .es6 through Bublé which is so damn fast and lot constrained than Babel, or, if you want to use Babel:

Run npm install babel-core@^6 babel-preset-es2015 to get the latest babel version with es2015 as default preset:

var tarima = require('tarima');
tarima.parse('x.es6.js', 'export default 42', {
  babel: {
    presets: [require.resolve('babel-preset-es2015')]
}).render(function(err, result) {
  console.log(err, result);

Globals (and data)

As part of the transpilation process you can put any value as global using the globals option:

tarima.parse('x.js', '/* global foo */console.log(foo);', {
  globals: {
    foo: 'bar'
}).render(function(err, result) {

The previous code will output this:

var foo = "bar";

All given globals are injected in the sample place as the /* global */ comment is declared.

Also you can pass any value, even functions, because all values are normalized through the tosource module.

Local data (either passed manually and front-matter) is always merged with globals, e.g.

foo: bar
/* global foo */

Resulting into:

var foo = "bar";

Using this technique your code will always be valid on syntax terms. ;)

The bundler will merge up all with the before processing.

Note globals are injected during the post-filterphase at entry-point level, see below.


Tarima handle sources this way: read -> pre-filter -> compile -> post-filter.

Passing a function as the filter option brings you the ability to modify the partial view during the pre-filter phase.


All supported templates can take locals, you can pass any values when calling .render(locals, cb) to draw them during the compile (or render) process.


support.getKnownExtensions() — Mixed extensions from all supported engines, e.g. ['.js', '.js.pug', '.js.rv.pug'] as used for resolving know sources.

support.getExtensions() — Raw extensions from all supported engines, e.g. ['js', 'md', 'ract'].

support.isSupported(filename) — True if the given filename is really supported for any registered engine.

support.isTemplate(extname) — True if the given extname is used primary for templates or views.

support.isScript(extname) — True if the given extname is used primary for scripts.

support.resolve(extname) — WIll resolve the most immediate engine that support the given extension.

Dependant tools