Introducing the Node.js Hogan Template Compiler module

13 May 2012

In my previous post I described why you should pre-compile your templates on the server.

I’ve just created the Hogan Template Compiler module which makes it easier to implement the entire process. It’s a simple framework-agnostic npm module which:

Pre-Compiles mustache templates and partials on the server.
Stringifies partials for use in the browser.

How the module works

The diagram below describes how you can compile your templates once on the server and then re-use them in the browser. This means that the browser never has to compile the templates.

hogan module

The Hogan Template Compiler reads the templates and partials
The browser requests the complete HTML page (including server-rendered partials).
The browser loads the pre-compiled partials (in the form of a simple JavaScript file).
The browser renders additional pre-compiled partials when needed.

Why pre-compiling and sharing templates is a good idea

There are heaps of benefits to pre-compiling and sharing templates! The biggest is performance.

Performance

Ajax onDomReady is suboptimal. It’s faster for the browser to display your web page if your server renders the entirety of every HTML response. This frees the browser from doing any additional ajax requesting or template compiling and rendering.

As an example, as it stands currently, if you go to someone’s twitter page then the static HTML file you’re served from the server is your own tweet stream, not of the user you’ve requested. The other user’s tweets are fetched via ajax and rendered over the top. This results in the pop you see when you first load the page.

Now, I’m not second-guessing Twitter’s choice in this matter as obviously there’s heaps of technical limitations running at their scale. However, if they could return the static HTML of the page you’ve requested, then your browsing experience would be better.

The Hogan Template Compiler allows you to render the entirety of your templates on the server making it possible to totally deliver every page of your site as quickly as possible. Subsequent rendering can be done in the browser with the shared pre-compiled partials which are created for you. They’re simply loaded as a JavaScript file.

SEO

Another benefit of having the entire page rendered server-side is that Google and other search engines can easily index all of your content.

One Template To Rule Them All

Using the very same templates for rendering on the server and in the browser means that there’s one source of truth for how your pages are rendered. Some of the sites I’ve worked on have had fragmented templating systems meaning I’d be forced to update the server-side and client-side templates separately.

Caching

Since the pre-compiled partials are delivered as a static JavaScript file, the browser will cache this for as long as you want it to.

How to use it

$npm install hogan-template-compiler

Load the module and point it to your partials directory:

var HoganTemplateCompiler = require('hogan-template-compiler'),
    templateDirectory = __dirname + "/views",
    hoganTemplateCompiler = HoganTemplateCompiler({
        partialsDirectory: templateDirectory + "/partials"
    });

Compile a template manually:

var compiledTemplate = hoganTemplateCompiler.compileTemplateFile(templateSourcePath);

Setup a route (in Express) to send the pre-compiled templates to the browser:

app.get("/templates.js",  function(req, res) {
    res.contentType(".js");
    res.send(hoganTemplateCompiler.getSharedTemplates());
});

For a working example with Express; try the following:

$ git clone https://[email protected]/dave-elkan/pre-compiled-hogan-templates.git
$ cd pre-compiled-hogan-templates
$ npm install -d
$ node app.js

Get the Source

Grab yourself a copy at https://github.com/dave-elkan/hogan-template-compiler

edave.net