handlebars_assets: Handlebars templates compiled as Rails assets

Templates stop being inline script tags

The problem this gem names is specific. Handlebars templates tend to end up inside script tags in Rails views, and the Rails 3.1 asset pipeline streams and caches all your JavaScript except those templates. handlebars_assets gives the templates their own files, including partials, and has them compiled, compressed and cached as part of the pipeline. The gain is consistency with the rest of the asset stack: one digest, one precompile step, one place where a template is edited. The gem is MIT licensed, the repository has no tagged releases, and the last push was on 2026-07-04. It also runs outside Rails. Sprockets users on Sinatra or another framework can use it, and the documentation says that has been possible since v0.2.0.

Three ways to add the gem, depending on your Rails version

The installation section splits by Rails version, and the differences matter. On Rails 4.0 and later the gem goes in the Gemfile as a normal dependency:

gem 'handlebars_assets'

On Rails 3.1 it belongs in the assets group:

group :assets do
  gem 'handlebars_assets'
end

The documentation flags a trap here: as of Rails 4.0 the assets group is not supported in the Gemfile, so a project upgrading from Rails 3.2 to Rails 4.0 has to move the entry out of the group. For a non-Rails Sprockets setup, the gem is added the same way and then its asset path is appended to the environment:

env = Sprockets::Environment.new

require 'handlebars_assets'
env.append_path HandlebarsAssets.path

That append_path call is required, since it is what tells Sprockets where the handlebars JavaScript files live.

The manifest order is not a style preference

In your JavaScript manifest you require the handlebars runtime, or the full library if you also want to compile templates in the browser:

//= require handlebars.runtime

Then you pull in your templates with require_tree:

//= require_tree ./templates

The documentation states two ordering constraints explicitly. The require_tree for templates must come before require_tree ., otherwise the templates do not get the intended prefix, and it must come after the handlebars or handlebars.runtime include. In other words, the templates block is positional, and a manifest edited by merging another branch can silently change what a template is called at run time. The template files themselves live wherever your other assets live, with app/assets/javascripts/templates given as the typical location.

What the pipeline does to a .hbs file

A template is a standalone file whose extension tells the pipeline how to process it. With .hbs, the pipeline compiles the Handlebars template to JavaScript and adds the resulting code to the HandlebarsTemplates global under a name derived from the path. For a file at templates/contacts/new.hbs the entry is registered as contacts/new, so your application code calls it like this:

HandlebarsTemplates['contacts/new'](context);

One detail catches people out and the documentation spells it out: there is no HandlebarsTemplates object at all unless at least one template is included. The gem also ships with the current stable release of handlebars.js, and there is a section on using another version if that release does not work for you, which matters when the runtime version in the gem drifts from the one your application code expects.

Partials, template namespaces and the Ember switches

Partials are recognised when the template file name starts with the _ character, and they are invoked with the Handlebars partial syntax, for example {{> path/to/_partial }}. The global that holds the compiled templates defaults to HandlebarsTemplates and can be renamed through the configuration, with JST given as a common alternative:

HandlebarsAssets::Config.template_namespace = 'JST'

There is also an Ember mode, which compiles the templates for use with Ember.js:

HandlebarsAssets::Config.ember = true

And a multi-framework mode for when the same application needs both:

HandlebarsAssets::Config.multiple_frameworks = true

Once multiple_frameworks is enabled, templates with the .ember.hbs extension are the ones made available to Ember. That per-extension routing is the reason the configuration schema changed, as noted in the breaking changes for v0.17.

Haml and Slim templates through different extensions

The extension carries the dialect as well as the language. A template named .hamlbars is written in Haml syntax and processed by the Haml rendering engine, with custom options passed to the Haml rendering engine through the HandlebarsAssets::Config.haml_options setting. The .slimbars extension does the same for Slim. The file itself looks like ordinary Haml with handlebars interpolation in the markup, which is the point: the template keeps the formatting language your team already writes in while still compiling to a registered handlebars template. If your project has moved templates to Haml or Slim to keep views consistent, this is what stops the templates from becoming the one exception to that rule. The trade-off is that the extension set now includes several variants, and the pipeline has to be told which one applies.

Precompiling, Heroku and the rake re-run

The gem works when you precompile assets, and the documentation is blunt about the cost. If you use rake assets:precompile, you have to re-run the rake command to rebuild any changed templates, because the precompiled output is not refreshed by anything else. For Heroku and similar cloud hosts, the application config needs a specific setting:

config.assets.initialize_on_precompile = false

That avoids running your initializers while assets are compiled, and the documentation notes the catch: it also means you cannot set your configuration in an initializer. Setting the option to true instead runs all initializers before precompiling, and the documentation points at a workaround in an open issue for the case where you need both. The practical read is that this gem lives inside a build step with sharp edges, and a team that regenerates assets only at deploy time will find template edits invisible until the next full precompile.

Where handlebars_assets is the wrong choice

The alternative approach is to skip build-time compilation entirely and let the browser do it, which the documentation already supports by letting you require handlebars.js instead of handlebars.runtime when you need to compile templates in the browser as well. The difference in approach is direct. Build-time compilation produces a template registered on a JavaScript global, with the template source compiled during the asset build and the shipped file small. Runtime compilation ships the full handlebars library, which the documentation notes is significantly larger, and compiles the template in the page, which is what you need if the template source changes at run time or arrives from somewhere the build never sees. Another boundary is the Rails version. A project on Rails 3.1 that wants to keep its assets group in the Gemfile cannot, because that group stopped being supported in Rails 4.0, and a project that has moved off the asset pipeline altogether has no use for this gem at all.

Editorial conclusion

handlebars_assets fits Rails and Sprockets applications that keep handlebars.js templates as separate files and want them compiled, compressed and cached with the rest of the assets, and it still works outside Rails through Sprockets. It does not fit projects that want templates compiled in the browser at run time, and it does not fit a Rails 3.1 setup that depends on the assets group in the Gemfile, since Rails 4.0 no longer supports that group. Before adopting it, check the manifest ordering rule, because require_tree ./templates has to sit after the handlebars require and before require_tree ., and remember that a changed template needs rake assets:precompile to be re-run.

Frequently asked questions

Official sources

1. Issues
2. leshill/handlebars_assets on GitHub
3. License: MIT
4. README