Handlebars Version Compatibility

– By Robert Jackson

Handlebars 2.0 was released a few weeks ago, and since its release we have received many requests to update Ember to allow the use of the latest version. Handlebars 2.0 contains a number of changes the list below represents a few that are likely to affect your Ember application:

  • Precompiler output has changed, which breaks compatibility with prior versions of the runtime and precompiled output.
  • A JSON polyfill is required to run the compiler in IE8 and below. It's recommended that the precompiler be used in lieu of running the compiler on these legacy environments.
  • Lines containing only block statements and whitespace are now removed. This matches the Mustache spec but may cause issues with code that expects whitespace to exist but would not otherwise.

For more information about the changes please review the release notes.

Since the release of Ember 1.0.0, Ember has required Handlebars 1.x. As each new version of Handlebars has been released we have needed to update our version requirement to allow the latest and greatest. Thankfully, throughout this process we have been able to maintain backwards compatibility with all versions of Handlebars since 1.0.0.

Unfortunately, Ember will not be able to maintain backwards compatibility to 1.x versions of Handlebars while supporting 2.0. In Ember 1.9.0 (which will be released to beta on October 24th and stable on December 5th) support for Handlebars 1.x will be removed, and support for Handlebars 2.0 introduced.

In order to facilitate users of our 1.9.0 builds we have published alpha versions of the following template precompiler packages:

  • ember-template-compiler (published to NPM as 1.9.0-alpha)
  • ember-source (published to Rubygems as 1.9.0.alpha)

Upgrading

To upgrade please use the following rough steps as a guide:

  • Update Handlebars version to 2.X.
  • Update template precompiler version to 1.9.0-alpha or later.
  • Report any issues you have on our issue tracker.

Ember CLI Steps

If you happen to be using Ember CLI the following steps should work properly:

  • npm uninstall --save-dev broccoli-ember-hbs-template-compiler
  • npm install --save-dev ember-cli-htmlbars@0.6.0
  • rm -rf bower_components
  • bower install --save handlebars#2.0.0
  • bower install --save ember#1.9.1
  • bower install