handlebars

library4.7.8.post20241027jsnpmunverified

Handlebars.js is a robust and widely-used JavaScript templating engine that facilitates the creation of semantic templates with minimal frustration. It is largely compatible with Mustache templates, allowing developers to often swap engines without major template modifications. The current stable version, 4.7.9, focuses on ongoing maintenance, including crucial security patches, bug fixes, and type definition enhancements within the 4.x series. Handlebars differentiates itself by providing powerful features such as custom helpers, block expressions, nested path support, and the ability to precompile templates for improved client-side performance. While striving for compatibility with Mustache, it introduces its own extensions and deviates in areas like recursive lookup, which requires an explicit `compat` flag. It is suitable for both browser and Node.js environments and ships with TypeScript type definitions, making it well-suited for modern JavaScript and TypeScript projects.

web-framework serialization

npm install handlebars

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · HANDLEBARS

handlebars

web-frameworkjavascriptv4.7.8.post20241027

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Handlebars

✓ import Handlebars from 'handlebars';

✗ import { Handlebars } from 'handlebars';

Handlebars is typically imported as a default export in ESM.

Handlebars (CommonJS)

✓ const Handlebars = require('handlebars');

✗ const { compile } = require('handlebars');

For CommonJS environments, the entire Handlebars object is usually imported. The `compile` method is accessed via `Handlebars.compile`.

TemplateDelegate (Type)

✓ import type { TemplateDelegate } from 'handlebars';

✗ import { TemplateDelegate } from 'handlebars';

Use `import type` to import only the type definition for `TemplateDelegate` for better bundler tree-shaking and clearer intent in TypeScript.

Demonstrates basic template compilation, data rendering, and the registration and usage of a custom helper with TypeScript types.

import Handlebars from 'handlebars'; interface Kid { name: string; age: string; } interface Context { name: string; hometown: string; kids: Kid[]; } const source = `<p>Hello, my name is {{name}}. I am from {{hometown}}. I have ` + `{{kids.length}} kids:</p>` + `<ul>{{#kids}}<li>{{name}} is {{age}}</li>{{/kids}}</ul>`; const template = Handlebars.compile<Context>(source); const data: Context = { "name": "Alan", "hometown": "Somewhere, TX", "kids": [{"name": "Jimmy", "age": "12"}, {"name": "Sally", "age": "4"}] }; const result = template(data); console.log(result); // Registering a custom helper Handlebars.registerHelper('loud', function(text) { return text.toUpperCase(); }); const helperSource = `<h1>{{loud name}}</h1>`; const helperTemplate = Handlebars.compile<Pick<Context, 'name'>>(helperSource); const helperResult = helperTemplate(data); console.log(helperResult);

handlebars --version

Debug

Known issues

breakingHandlebars.js version 4.7.9 fixes a critical JavaScript Injection vulnerability (GHSA-2w6w-674q-4c4q / CVE-2026-33937). An attacker could achieve Remote Code Execution by supplying a crafted Abstract Syntax Tree (AST) to `Handlebars.compile()` if user-controlled input was not properly sanitized.

fix

Upgrade to Handlebars.js version 4.7.9 or newer immediately. Ensure any user-controlled input passed to `Handlebars.compile()` is always a string and not a parsed object/AST. Consider using the runtime-only build (`handlebars/runtime`) if templates are pre-compiled.

affects: <4.7.9

breakingAccess to prototype properties is strictly forbidden by default since version 4.6.0, and more rigorously enforced with `strict: true` in later 4.x versions. This change prevents prototype pollution attacks. Code relying on implicit prototype chain lookups will break.

fix

Update templates to use explicit path references instead of relying on prototype chain traversal. If absolutely necessary, specific properties or methods can be allowed via runtime-options, but this is discouraged.

affects: >=4.6.0

gotchaHandlebars does not perform recursive lookup by default, a subtle difference from Mustache. Enabling the `compat` compile-time flag restores this behavior but incurs a performance cost.

fix

For optimal performance, explicitly reference paths in templates (e.g., `{{../parent.property}}`). If Mustache-style recursive lookup is critical, enable the `compat` option during compilation, being mindful of the performance implications.

affects: >=4.0.0

gotchaOlder versions of Handlebars (e.g., prior to 4.7.8) had known issues with modern bundlers like Rollup and Webpack 5 when importing as an ESM module.

fix

Ensure you are using at least Handlebars v4.7.8 or newer to benefit from fixes addressing bundler compatibility with ESM imports. Verify your bundler configuration to correctly handle ESM and CommonJS interop.

affects: <4.7.8

Errors

Common errors & fixes

ReferenceError: Handlebars is not defined

The Handlebars library was not imported or included correctly in the execution environment (e.g., missing `require` or `import` statement, or not included in a browser script tag).

fix

In Node.js or modern environments, add `import Handlebars from 'handlebars';` (ESM) or `const Handlebars = require('handlebars');` (CommonJS). In the browser, ensure the Handlebars script is loaded before your application code.

Error: Missing helper: 'myCustomHelper'

A custom helper was used in a template but not registered with `Handlebars.registerHelper()` before template compilation or rendering.

fix

Register your custom helper function globally using `Handlebars.registerHelper('myCustomHelper', myFunction);` or pass it as an option to the `compile` or `render` method, ensuring it's available in the template's scope.

Template compilation error: Parse error on line X: Expected EOF, got '{{'

There is a syntax error in your Handlebars template (e.g., unclosed block, invalid helper syntax, malformed expression).

fix

Carefully review the template syntax around the indicated line number. Common issues include unclosed `{{#block}}...{{/block}}`, `{{^invertedBlock}}...{{/invertedBlock}}`, `{{else}}` placement, or incorrect helper arguments.

TypeError: Cannot read properties of undefined (reading 'length')

The template is attempting to access a property (like `length`) on a data variable that is `undefined` or `null` within the provided context.

fix

Ensure that the data object passed to the template function contains all expected properties, or implement checks within the template (e.g., `{{#if someArray.length}}{{/if}}`) to gracefully handle missing or undefined data.

Upgrade

Version history

4.7.8.post20241027latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/handlebars-lang/handlebars.js ↗

packagehttps://www.npmjs.com/package/handlebars ↗

homepagehttps://handlebarsjs.com ↗