wontache

Wontache

Compact, spec-compliant Mustache implementation with extras

Wontache is a fast, precompiling implementation of the Mustache templating language for JavaScript, written in just a few hundred lines of literate CoffeeScript. It fully implements version 1.2.2 of the Mustache specification, including the lambda and inheritance extensions, as well as some extra features which are listed further down below. An up-to-date reference of the Mustache templating language is available over here.

Compared to:

• Handlebars.js, Wontache is much smaller, substantially faster and faithful to Mustache's original syntax and semantics.
• Mustache.js, Wontache is much more accurate at indentation handling, substantially faster and committed to adhere to the official specification.
• Hogan.js, Wontache is more up-to-date with the specification, more accurate at indentation handling and a bit faster on average, but overall similar in spirit. While I was unaware of Hogan.js when I started writing Wontache and the libraries have no common heritage, I hope that Wontache can be a worthy successor of Hogan.js, which is end-of-life.

The above claims are based on extensive benchmarks and rendering comparisons. There is no user-friendly presentation of the comparison yet, but if you wish, you can inspect the comparison source code. Of course, the best way to determine how Wontache performs in your application is to try it.

Development status

The 0.x release series is intended for evaluation. Wontache already completely implements the latest Mustache specification and is fully tested. Templates that compile in Wontache 0.x are expected to also compile in the 1.x release series and should mostly produce the same output. However, the interface has not fully stabilized yet. Among other things, this means that you might need to recompile your templates when Wontache is updated.

Most of the current development work is focused on adding production-friendly conveniences, such as TypeScript and Flow type declarations, a command line tool and integrations for various code bundling tools. More extensive documentation is planned as well. You can track progress towards the official launch over here.

Extras

• Intelligently handles block indentation in the context of inheritance, in accordance with a proposed extension by the author.
• new in version 0.1.0 Implements dynamic names in partials and parents, allowing you to write {{>*name}} to mean that name should be looked up in the context to find the actual name of the partial that should be interpolated. name may also be a dotted name or the implicit iterator ..

You can track planned extras over here.

Quickstart

import mustache from 'wontache';

const template = '{{#people}}Hello {{name}}!\n{{/people}}';
const data = {
    people: [
        {name: 'Alice'},
        {name: 'Bob'},
    ],
};

const templateFunction = mustache(template);
console.log(templateFunction.source);
// mustache({sections: [function(state){...}, ...]})
// (useful for bundling templates with JavaScript)

const output = templateFunction(data);
// Hello Alice!
// Hello Bob!

// You can also do a double call for a quick one-off:
output = mustache(template)(data);

Build variants

Wontache has several build variants. If you use the package in Node.js or bundle it with a Node.js-aware tool such as Rollup, WebPack or Browserify, the right build variant will be selected automatically. In other situations, such as loading from a CDN, using an AMD loader or usage in deno, you may need to select a build variant explicitly. The following build variants are of interest outside of Node.js:

• mustache-umd.js is an old-fashioned UMD module. When not using CommonJS or AMD, the mustache function is globally available as _.mustache. The global name is still subject to change.
• mustache-esm.js is an ES module that imports the Underscore library as a monolithic interface. This variant is appropriate for direct use in ESM environments.
• module.js is an ES module that imports individual Underscore functions from their respective modules. This variant is suitable for inclusion in a custom Underscore. More on Underscore below.

Underscore dependency

Wontache depends on Underscore for some utility functions. This enables us to write shorter, more maintainable, more portable and higher quality code than if the library was dependency-free. We encourage everyone to embrace Underscore (and other libraries) for these same reasons.

If you are concerned about dependency size, you can use the module.js build variant in order to enable treeshaking. This is the module entry in the package.json, so bundlers like Rollup and WebPack will find it automatically. The subset of Underscore that Wontache depends on is only about 190 lines of ES3, including blank lines and comments.

Alternatively, the package includes a customUnderscore subdirectory with an index.js that lists all of our direct and indirect Underscore dependencies. You can use this in order to compose your own custom Underscore.

Wontache should also work with Lodash, although this is untested.

Manual

Compilation

The default and only export is a function that we call mustache by convention. It takes a Mustache template string as first argument and returns the compiled template as a function:

import mustache from 'wontache';

var compiled = mustache('template with {{variable}}');

Rendering

The compiled template function takes the input data as its first argument. This can be any JavaScript value. Values to interpolate in the template are taken from the data. The template function returns a string with the final result of the template, given the data.

compiled({variable: 'flair'});
// 'template with flair'

Precompilation

The compiled template has a source property with a string representation of its source code. This can be used for ahead-of-time compilation, enabling you to compile each template once at build time and then (for example) send it to a browser where it will be executed many times.

compiled.source;
// mustache(function(state) {
//     return "template with " + state.v(["variable"]);
// })
// (The above source has been simplified for illustration.)

Keep in mind that the precompiled template code is larger than the original template text. You save startup time at the receiving end, at the expense of transferring more data.

The compiled template needs to have access to mustache at runtime. There are two main reasons for this: firstly, mustache provides runtime support functions, and secondly, some features of the Mustache template language require runtime recompilation of templates. If you are precompiling templates for later execution in a separate JavaScript session, make sure to import mustache in the module that contains your precompiled template.

Changing the delimiters

The {{ and }} default delimiters were chosen for a low probability of conflict with other computer languages. However, a conflict is still possible, for example when the template is meant to generate LaTeX code, or when you are writing a template that includes example Mustache template code that should be rendered verbatim. In such cases, you can change the delimiters.

The normal way to change the delimiters is by including a Set Delimiter tag in the template text. This is recommended in most cases, because this ensures your templates are portable to other Mustache implementations. It also gives you the freedom to switch delimiters halfway through a template, even multiple times if necessary.

var template = '{{=< >=}} template with <variable>';
var compiled = mustache(template);

However, you may have a large application with many templates. If there is a specific, alternative set of delimiters that you are consistently using in each of them, you probably don't want to start each template with the same Set Delimiter tag. For this purpose, you can pass the alternative delimiters as a second argument to mustache instead.

var template = 'template with <variable>';
var compiled = mustache(template, ['<', '>']);

If you are also calling mustache in many places, you can wrap the function so you don't have to explicitly pass the delimiters every time:

var myMustache = template => mustache(template, ['<', '>']);

// Equivalent, using Underscore:

import _, { partial } from 'underscore';

var myMustache = partial(mustache, _, ['<', '>']);

// usage in either case:

var compiled = myMustache('template with <variable>');

Partials

The Partial and Parent tags let you render and interpolate a template inside another template. If your templates contain either of those tags, you have to do some administration so that compiled templates are able to find each other by name. This administration takes the form of an object, where each key is the name of a template that may be embedded. The corresponding value may be either a template string or a template function (if you set a template string, it will be compiled on first use).

// The administration.
var namedTemplates = {
    link: '<a href="{{&url}}">{{title}}</a>'
};

// A template that will need the above administration.
var template = '<ul>{{#.}}<li>{{>link}}{{/.}}</ul>';
var linkList = mustache(template);

// The data.
var links = [{
    url: 'https://jgonggrijp.gitlab.io/wontache/',
    title: 'Wontache home page'
}];

There are two possible ways to make the partial administration available to a template function. The most hygienic way is to pass an object with a partials property as the second argument in the call to the template. This approach is strongly recommended for library authors, because it ensures that the partials provided to your template are completely isolated from the partials that other libraries or the application may be using.

linkList(links, {partials: namedTemplates});
// '<ul><li><a href="https://jgonggrijp.gitlab.io/wontache/">Wontache home page</a></ul>'

If desired, you can write a wrapper function that always passes the same partial administration to a given template function.

function render(templateFunc, data) {
    return templateFunc(data, {partials: namedTemplates});
}

render(linkList, links);
// Same output as above ('<ul><li><a href="...</a></ul>').

The most convenient way is to assign your administration to mustache.partials. Template functions automatically fall back to this if you don't pass a set of partials explicitly, so it can be "set and forget". This approach is intended for application authors. When using it, do keep in mind that mustache.partials is easy to compromise, by overwriting either one of its keys or the property as a whole. In principle, a sloppy library author could do this as well. You may even want to dedicate a test to ensuring that mustache.partials is complete.

Object.assign(mustache.partials, namedTemplates);
// Could also use Underscore's _.extend for compatibility.

linkList(links);
// Same output again ('<ul><li><a href="...</a></ul>').

Decompilation

Since templates sometimes need to be recompiled, there is a "backdoor" of sorts to reconstruct the original template text from the compiled function. While this is mostly an implementation detail, it might occasionally be useful for debugging purposes.

compiled(null, {decompile: true});
// 'template with {{variable}}'

Credits

The name "Wontache" was suggested by my dear friend Arie de Bruin.

Changelog

monorepo (whole project) 0.1.0

Initial released version of the project, including:

• wontache 0.0.1
• website with index page and manpage
• unfinished comparison workspace
• internal tools runcoffee and wrap-readme