Ship the Runtime, Not the Compiler: Precompiling Handlebars Templates

The compiler is dead weight in the browser

When a browser downloads the full Handlebars library, it receives more than the code needed to render HTML. It receives a template parser, an abstract syntax tree (AST) builder, and a code generator. If your templates are static files known at build time, every visitor pays for machinery they never need. Precompiling Handlebars templates moves that work to your build pipeline: the browser receives a small runtime and plain JavaScript functions that return HTML strings.

What precompilation actually emits

At runtime, Handlebars.compile(templateString) tokenizes the input, builds an AST, and generates a JavaScript function. That function is then cached and invoked with a context object. Precompilation runs the same compiler locally during your build, emits the resulting functions, and discards the compiler itself. The browser only needs handlebars.runtime.js, which knows how to execute those functions but cannot parse new template strings.

The Handlebars CLI can process individual files or entire directories. For a directory of .hbs files, it can produce a single registration module. The output format matters: CommonJS for bundlers like webpack or Rollup, AMD for RequireJS, or a browser global for simple script tags. Regardless of format, the emitted module registers each template by name. When your application code calls Handlebars.templates['user-profile'](context), it invokes the precompiled function directly.

A minimal build setup

Assume you have a templates/ directory with greeting.hbs and a partial at templates/partials/footer.hbs. Run the following from your project root. It requires Node.js and the handlebars package installed as a local dev dependency.

npm install --save-dev handlebars
npx handlebars templates/ -f dist/templates.js -c

Here, templates/ is the input directory, dist/templates.js is the output bundle, and -c selects the CommonJS module format. If you load scripts without a module bundler, choose a different output format instead. The expected check is straightforward: dist/templates.js should exist and contain registered template functions. If your templates reference {{> footer}}, the partial file must be compiled and registered under the exact name footer. When batch-processing a directory, the CLI derives names from file paths, so inspect the generated module to confirm the registration string matches your template calls.

In your application entry point, import the runtime once, then import the generated bundle to register everything:

import Handlebars from 'handlebars/runtime';
import './dist/templates.js';

const html = Handlebars.templates.greeting({ name: 'Reader' });

The main risk here is module format mismatch. If you emit CommonJS but load the file as a plain browser script, the code will fail because module and require are undefined. Match the output format to your loader.

The version coupling trap

Precompiled templates are not portable across Handlebars versions. They are JavaScript functions that call runtime helper methods by internal name. If your build pipeline uses one version of the compiler to generate them, but the browser loads a different version of the runtime, the output may be subtly wrong or throw exceptions. The compiler and runtime must match exactly. This is the most common failure mode when upgrading Handlebars in one place but not the other.

Precompilation also does not apply when templates arrive as raw strings from an API or are generated dynamically at runtime. In those cases you must ship the full compiler.

Verifying the switch

1. Version match. Run npx handlebars --version in your terminal and compare it to the version banner inside handlebars.runtime.js. They must be identical.
2. Output diff. In Node, require the precompiled module, render a template with a sample context, and compare the HTML string against Handlebars.compile(rawTemplate)(sameContext). They should match byte-for-byte.
3. Partial names. Open the generated JS file and search for registerPartial. Confirm the strings match every {{> name}} in your templates.
4. Bundle size. Compare your browser bundle before and after replacing the full handlebars.js with handlebars.runtime.js plus the precompiled output.

Treat precompilation as a build contract: lock the compiler and runtime versions together, verify partial names, and diff the output once. After that, the browser stops paying for a parser it never uses.