Feb 5, 2015 – By Robert Jackson

As many of you know, Ember 1.10 will be the first version of Ember that uses HTMLBars as its templating engine. With this change you may need to change the way you compile your templates.

The HTMLBars API is evolving and not 1.0.0 yet, so to ensure that templates are compiled compatibly with your Ember version we have updated the Ember build system to generate a ember-template-compiler.js file alongside every build of Ember. This template compiler can be used server-side for precompilation or in the browser to compile templates on the fly. If you do not need to compile templates at runtime (in the browser) the ember.debug.js or ember.prod.js file alone is sufficient. There is no need to include a runtime dependency. This is a departure from previous versions, where you would always include either handlebars.js or handlebars.runtime.js.

Most of the time you will use a third party library like ember-cli, ember-cli-htmlbars, or grunt-ember-templates to precompile templates, but this post will discuss how libraries like this should work internally.

Server Side Compilation

If possible, it is definitely a best practice to compile your templates server side. This is much faster due to less total size (you don't need the compiler on the client) and less work that the app needs to do.

Ember 1.0 through 1.9

In prior versions, you would typically use the ember-template-compiler NPM package that corresponded to your Ember version to precompile your templates. That might look something like the following:

var fs = require('fs');
var compiler = require('ember-template-compiler');
var input = fs.readFileSync('path/to/template.hbs', { encoding: 'utf8' });
var template = compiler.precompile(input, false);
var output = 'export default Ember.Handlebars.template(' + template + ');';

fs.writeFileSync('path/to/output.js', output, { encoding: 'utf8' });

You would also need to include handlebars.runtime.js in your final build

Ember 1.10+

With Ember 1.10, you will use the ember-template-compiler.js file that is paired with your Ember version. If you use our Bower repo or RubyGem, or download Ember from our builds site, there is a ember-template-compiler.js in the same path as ember.debug.js and ember.prod.js.

You can use this template compiler directly and without additional requirements. For example:

var fs = require('fs');
var compiler = require('./bower_components/ember/ember-template-compiler');
var input = fs.readFileSync('path/to/template.hbs', { encoding: 'utf8' });
var template = compiler.precompile(input, false);
var output = 'export default Ember.HTMLBars.template(' + template + ');';

fs.writeFileSync('path/to/output.js', output, { encoding: 'utf8' });

As you will notice, the new API for server-side compilation is nearly identical to that of prior versions. The main change is the usage of the local bower_components/ember/ember-template-compiler.js file as opposed to the NPM module.

Client Side Compilation

Generally speaking, you should avoid compiling templates on the client, but there are times that you cannot avoid this. Live demo apps like JSBin are one example.

Ember 1.0 through 1.9

In prior versions of Ember you would need to ensure that the full version of Handlebars.js was present to allow compiling of templates. Perhaps something like the following in your index.html:

<script src="assets/handlebars.js"></script>
<script src="assets/ember.prod.js"></script>

Ember 1.10+

With Ember 1.10, you will include the ember-template-compiler.js for your specific Ember version. Something like the following:

<script src="assets/ember-template-compiler.js"></script>
<script src="assets/ember.prod.js"></script>

If you include the ember.debug.js file instead of a production file the compiler is still required.

Template Compilation Build Tools

There are any number of build tool libraries that are intended to make the server side compilation of templates easier. Here are a few (please let us know of others):

• ember-cli-htmlbars - Can be used either as a standalone Broccoli plugin, or as an ember-cli addon.
• grunt-ember-templates - Works as a Grunt plugin. To precompile HTMLBars templates, you must supply specific parameters to your task definition as mentioned in this PR.
• mimosa-ember-htmbars - A plugin for the mimosa build tool.
• ember-rails - The Rails Asset Pipeline plugin supports HTMLBars templates.