handlebars-loader

1.7.3 verified Sat Apr 25 auth: no javascript

A webpack loader for Handlebars templates that automatically resolves partials and helpers relative to the current file or via module prefixes. Version 1.7.3 is stable with infrequent releases; supports Handlebars 3.x and 4.x. Differentiators include automatic resolution, inline require support, and configurable directories for helpers/partials. Notable: v1.7.3 updates loader-utils dependency to address security vulnerabilities.

Common errors

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

cause Handlebars is a peer dependency and must be installed separately.

fix

Run npm install handlebars --save-dev.

error ERROR in ./template.handlebars 1:0 Module parse failed: Unexpected token (1:0) ↓

cause The loader is not correctly configured in webpack, or the test regex does not match the file extension.

fix

Ensure your webpack config has a rule with test: /\.handlebars$/ and loader: 'handlebars-loader'.

error Cannot find module 'handlebars/runtime' ↓

cause The runtime path is not resolved correctly when using `runtime` option or default resolution fails.

fix

Set the runtime option explicitly: options: { runtime: 'handlebars/dist/cjs/handlebars.runtime.js' }.

Warnings

breaking Webpack 4+ removed the deprecated `loader` property in favor of `use` in module rules. ↓

fix Use `use: 'handlebars-loader'` or `loader: 'handlebars-loader'` inside a `use` array.

deprecated The `inlineRequires` option requires disabling `esModule` in file-loader/webpack5 asset modules. ↓

fix Set `esModule: false` in your file-loader config or use `type: 'javascript/auto'` for asset modules.

gotcha Partials and helpers are resolved relative to the current template unless prefixed with `$` to denote a module. ↓

fix Use `{{> $module/partial}}` for node_modules partials, or set `rootRelative` option.

breaking Upgrading from webpack 1 to 2+ requires changing `loaders` key to `rules` and `loader` to `use`. ↓

fix Update webpack config to use `module.rules` array.

Install

npm install handlebars-loader

yarn add handlebars-loader

pnpm add handlebars-loader

Imports

default

wrong

const template = require('./file.handlebars');

correct

import template from './file.handlebars';

Use ESM import syntax with webpack 2+.

default (for webpack config)

wrong

module.exports = { module: { loaders: [ { test: /\.handlebars$/, loader: 'handlebars-loader' } ] } };

correct

module.exports = { module: { rules: [ { test: /\.handlebars$/, loader: 'handlebars-loader' } ] } };

Webpack 2+ uses 'rules' instead of 'loaders'.

no direct import

wrong

import handlebarsLoader from 'handlebars-loader';

correct

This loader is not imported directly by user code; it is referenced in webpack config.

Do not import the loader in your entry files; it's used internally by webpack.

Quickstart

Shows installation, webpack configuration with common options, and usage of a Handlebars template in a JavaScript entry file.

npm install handlebars-loader handlebars --save-dev

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.handlebars$/,
        loader: 'handlebars-loader',
        options: {
          knownHelpers: ['if', 'unless', 'each', 'with', 'lookup'],
          helperDirs: ['/path/to/helpers'],
          partialDirs: ['/path/to/partials'],
          debug: true
        }
      }
    ]
  }
};

// entry.js
const template = require('./template.handlebars');
document.body.innerHTML = template({ name: 'World' });