What are the differences between the Handlebars 1.x and 2.x APIs?

Question

We are currently using Handlebars version 1.3.0 in production, and I'd like to know what, if anything, we'll need to change in order to be able to upgrade to version 2.x. Since the HandlebarsJS team is committed to semantic versioning I know there must be some breaking changes, but I don't see them listed in the README.md. There are some items listed in the changelogs for the v2.0.0-alpha.N releases, but it's not clear to me whether or not this is a complete list (or if a complete list would even exist before 2.0.0 final is released). Some of the 1.x releases have "compatibilty notse" sections as well, but I believe they are all non-breaking/forward-compatible.

Could anyone offer some insight into the API differences or the goals/improvements of the 2.x series?

Compatiblity Notes

• A JSON polyfill is required to run the compiler under IE8 and below. It's recommended that the precompiler be used in lieu of running the compiler on these legacy environments.

  ---

• helperMissing helper no longer has the indexed name argument. Helper name is now available via options.name.
• Precompiler output has changed, which breaks compatibility with prior versions of the runtime and precompiled output.
• JavaScriptCompiler.compilerInfo now returns generic objects rather than javascript source.
• AST changes
  • INTEGER -> NUMBER
  • Additional PartialNode hash parameter
  • New RawBlockNode type
• Data frames now have a _parent field. This is internal but is enumerable for performance/compatability reasons.

Update: From the ember.js blog on 10/16/2014

In addition to the changes noted above:

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.

Answer 1

If you look at changes between v1.3.0 and v2.0.0-alpha.1 releases of Handlebars accordingly to official Release Notes you will see, that was two major changes, that would break your templates during upgrade.

1. Precompiler output has changed, which means your 1.x precompiled templates would not be compatible with Handlebars 2.x runtime, as well as 2.x runtime will be not compatible with old templates. You should update precompiler, update runtime and update all templates.
2. Partials no longer have access to parent context (../), but now can accept hash as argument and has access to the root context through @root variable. So look at your partials for using ../ and change it to using local data, passed to partial as argument.

So, that's the main things you should pay attention when upgrading to 2.x Handlebars version. There was some internal changes which affect helperMissing helper, JavaScriptCompiler.compilerInfo, updates AST and data frames. But all of that makes sense only for users, who uses their own forks or making some of the modifications in runtime. Other changes was primarily bugfixes.