Handlebars.js

Handlebars is a logic-less templating engine that extends Mustache syntax with helpers, partials, and block expressions for building semantic HTML and text templates. It compiles templates into JavaScript functions ahead of time, so rendering stays fast even when the same template is reused across thousands of requests.

Widely adopted since 2010, it now powers templating inside Ember.js, Ghost, and Assemble, plus dozens of Express/Koa view-engine adapters, and it ships both browser and Node.js runtime builds along with a CLI for precompiling templates into static functions.

What You Get

• A compiler that turns {{mustache}}-style templates into optimized, precompiled JavaScript render functions
• A registry of built-in block helpers (each, if, unless, with, lookup) plus a public API for registering custom helpers, partials, and decorators
• Separate runtime-only and full builds so precompiled templates can ship to browsers without bundling the compiler
• A handlebars CLI binary for precompiling template directories into a single JS or source-map bundle ahead of deployment

Common Use Cases

• Server-side HTML rendering in Express/Koa apps via adapters like express-handlebars or hbs
• Static site generation, where tools like Assemble use Handlebars as the page and layout template engine
• Precompiling email or document templates once at build time to avoid runtime parsing overhead
• Client-side view rendering, historically as the templating layer inside Ember.js

Under The Hood

Architecture Handlebars separates parsing, compilation, and execution into distinct layers connected through a small create() factory (lib/handlebars.js). Source text first passes through the external @handlebars/parser package to produce an AST (lib/handlebars/compiler/ast.js), which the Compiler (lib/handlebars/compiler/compiler.js) walks to emit a linear opcode stream; JavaScriptCompiler (lib/handlebars/compiler/javascript-compiler.js) then lowers those opcodes into a JavaScript function body via code-gen.js, so a template ultimately becomes a plain callable function rather than an interpreter walking the AST at render time. The runtime half (lib/handlebars/runtime.js, lib/handlebars.runtime.js) is deliberately kept separate from the compiler so precompiled templates can execute in a browser bundle that never ships the parser/compiler code. Helpers, partials, and decorators are managed as registries on the instance (lib/handlebars/helpers.js, lib/handlebars/decorators.js) that both built-ins (each, if, with, lookup, block-helper-missing) and user code register into via registerHelper/registerPartial, giving a single extension point that both the compiler (for known-helper optimization) and runtime (for dynamic lookup) consult.

Tech Stack The library is pure JavaScript (94% by bytes) with a thin TypeScript typings layer (types/index.d.ts, checked via tstyche), distributed as native ESM ("type": "module") with explicit exports map entries for the full build and a ./runtime-only subpath. It depends on @handlebars/parser for tokenizing/parsing, source-map for source-map generation during precompilation, neo-async for internal async control flow, and yargs to power the bin/handlebars.js CLI. The build pipeline uses rspack (not webpack) for bundling, oxlint/oxfmt (Rust-based, not ESLint/Prettier) for linting and formatting, and vitest with multiple named projects (node, browser via Playwright, rspack, tasks, publish) plus @vitest/coverage-v8 for coverage — a notably modern, fast tool stack relative to the library’s 2010 origins.

Code Quality Testing is extensive: 44 spec/test files under spec/ and tests/, covering compiler output, helpers, partials, security, whitespace control, and Mustache-spec conformance, run across four vitest projects plus a Playwright browser-smoke suite. eslint-plugin-compat is scoped specifically to lib/** to catch browser API compatibility regressions, separate from the broader oxlint pass. Error handling is centralized through a single Exception type imported from @handlebars/parser and thrown with descriptive, actionable messages (23 call sites in lib/handlebars), e.g. explicit guidance when a precompiled template’s compiler revision doesn’t match the runtime. Code style is consistent (2-space indent, small single-purpose modules per helper), and husky + lint-staged enforce formatting/linting on commit.

API Design The public surface is intentionally small and stable: compile()/precompile() for turning template strings into functions, registerHelper/registerPartial/registerDecorator for extension, and a create() factory for isolated instances — this has stayed largely unchanged since the library’s early versions, which is why so many downstream adapters (express-handlebars, ember, ghost) can depend on it directly. Named exports are re-exported individually in lib/index.js specifically to keep CJS interop working under Node’s ESM/CJS boundary, showing deliberate attention to consumer ergonomics during the project’s ESM migration. Documentation lives primarily on the external handlebarsjs.com site rather than inline JSDoc, with only two markdown files (compiler-api.md, decorators-api.md) in-repo for lower-level extension APIs; the README leans on runnable examples rather than exhaustive API reference, which suits its “compile once, call like a function” mental model well.