handlebars-template-loader

1.1.0 verified Sat Apr 25 auth: no javascript

A Handlebars template loader for Webpack. Current stable version is 1.1.0 (last updated 2024). It allows you to require .hbs files and use them as compiled templates, with support for helpers, partials, macros, and image loading. Key differentiators: includes macros like require, include, repeat; options for prepending filename comment for debugging; supports custom Handlebars runtime path. Release cadence is low, with infrequent updates. Note: does not bundle Handlebars, so you must install it separately.

Common errors

error Error: Cannot find module 'handlebars' ↓

cause Handlebars is not installed; it's a peer dependency since v0.5.4.

fix

Run 'npm install handlebars'

error Error: Module not found: Error: Can't resolve 'fs' ↓

cause Webpack tries to bundle Node.js 'fs' module, which is not available in browser.

fix

Add 'node: { fs: "empty" }' to webpack config.

error Handlebars is not defined ↓

cause Using 'require('handlebars')' directly instead of the loader's runtime module.

fix

Use 'const Handlebars = require('handlebars-template-loader/runtime')'

Warnings

breaking Version 1.0 only supports Webpack 4. ↓

fix Use webpack 4. For older webpack versions, use version 0.x.

gotcha Handlebars is NOT bundled. You must install it separately (peer dependency). ↓

fix Run 'npm install handlebars --save' in your project.

gotcha The 'node.fs' must be set to 'empty' in webpack config to avoid errors. ↓

fix Add 'node: { fs: "empty" }' to webpack config.

gotcha Images with absolute paths are not translated unless 'root' option is defined. ↓

fix Set 'query: { root: __dirname }' or use relative paths.

Install

npm install handlebars-template-loader

yarn add handlebars-template-loader

pnpm add handlebars-template-loader

Imports

default
wrong
```
import loader from 'handlebars-template-loader'
```
correct
```
require('handlebars-template-loader')
```
This package does not provide ESM exports; use CommonJS require in webpack config.
runtime
wrong
```
const Handlebars = require('handlebars')
```
correct
```
const Handlebars = require('handlebars-template-loader/runtime')
```
Use the runtime module to get the same Handlebars instance used by the loader for registering helpers and partials.

partial

wrong

Handlebars.registerPartial('name', require('path/to/_partial.hbs'))

correct

const partial = require('path/to/my/_partial.hbs'); Handlebars.registerPartial('name', partial)

The compiled partial is a function; register it directly.

Quickstart

Sets up the loader in webpack config and shows a basic template compilation and rendering.

// webpack.config.js
module.exports = {
  module: {
    rules: [
      { test: /\\.hbs$/, loader: 'handlebars-template-loader' }
    ]
  },
  node: { fs: 'empty' }
};

// app.js
const tmpl = require('./hello.hbs');
document.body.innerHTML = tmpl({ name: 'World' });

// hello.hbs
<p>Hello {{name}}</p>