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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
default
✓ import template from './file.handlebars';
✗ const template = require('./file.handlebars');
Use ESM import syntax with webpack 2+.
default (for webpack config)
✓ module.exports = { module: { rules: [ { test: /\.handlebars$/, loader: 'handlebars-loader' } ] } };
✗ module.exports = { module: { loaders: [ { test: /\.handlebars$/, loader: 'handlebars-loader' } ] } };
Webpack 2+ uses 'rules' instead of 'loaders'.
no direct import
✓ This loader is not imported directly by user code; it is referenced in webpack config.
✗ import handlebarsLoader from 'handlebars-loader';
Do not import the loader in your entry files; it's used internally by webpack.
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' });
Errors
Common errors & fixes
Module not found: Error: Can't resolve 'handlebars'
Handlebars is a peer dependency and must be installed separately.
fixRun `npm install handlebars --save-dev`.
ERROR in ./template.handlebars 1:0 Module parse failed: Unexpected token (1:0)
The loader is not correctly configured in webpack, or the test regex does not match the file extension.
fixEnsure your webpack config has a rule with `test: /\.handlebars$/` and `loader: 'handlebars-loader'`.
Cannot find module 'handlebars/runtime'
The runtime path is not resolved correctly when using `runtime` option or default resolution fails.
fixSet the `runtime` option explicitly: `options: { runtime: 'handlebars/dist/cjs/handlebars.runtime.js' }`. Audit
Dependencies
handlebarsrequiredPeer dependency; runtime used by generated templates.
loader-utilsrequiredRequired by webpack loaders for utility functions.