node package manager

tarima

Templating madness!

Tarima

$ 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.

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

Example:

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) — 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.

Example:

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

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.

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>

Output:

<div><h1>Untitled</h1></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.

You can install the following dependencies for specific support:

  • npm install coffee-script.coffee and .litcoffee (aka .coffee.md)
  • npm install postcss.post.css 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 kramed.md, .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.

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);
});

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) {
  console.log(result.source);
});

The previous code will output this:

var foo = "bar";
console.log(foo);

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 */
console.log(foo);

Resulting into:

 
var foo = "bar";
console.log(foo);

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

The bundler will merge up all importee.data with the importer.data 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.