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.
CLI Commands
✓ npm install -g ya-handlebars-bundler
handlebars-init
handlebars-watch
✗ import { handlebarsWatch } from 'ya-handlebars-bundler'
ya-handlebars-bundler is primarily a command-line interface tool. It is installed globally or locally and invoked via its CLI commands, not directly imported into JavaScript code. The generated bundle is then consumed.
Handlebars.templates
✓ const Handlebars = require('handlebars');
require('./handlebars.bundle.js');
const html = Handlebars.templates.myTemplate({});
✗ import { templates } from 'handlebars.bundle.js';
const html = templates.myTemplate({});
After the generated `handlebars.bundle.js` is loaded (via `require` or `<script>`), it populates the global or imported `Handlebars` object. Templates are then accessed through `Handlebars.templates` (or `Handlebars.partials`). Ensure the `handlebars` library is loaded *before* the bundle in browsers.
Handlebars.partials
✓ const Handlebars = require('handlebars');
require('./handlebars.bundle.js');
const partialHtml = Handlebars.partials['my/nested/partial']({});
✗ import { partials } from './handlebars.bundle.js';
const partialHtml = partials['my/nested/partial']({});
Similar to templates, partials are exposed on the `Handlebars` object. The bundle automatically registers partials under their respective paths (e.g., `nes/ted/kitty` for `~/myapp/partials/nes/ted/kitty.hbs`). The main `Handlebars` library must be present first.
This quickstart guides through global installation, project initialization with default configuration, continuous bundling, and how to consume the generated Handlebars bundle in a Node.js environment.
/* Install globally */
npm install -g ya-handlebars-bundler
/* Create a new project directory */
mkdir my-handlebars-app
cd my-handlebars-app
/* Initialize default configuration and example files */
handlebars-init
/* Review and adjust handlebars.config.js */
// module.exports = {
// entry: {
// helpers: 'helpers',
// partials: 'partials',
// templates: 'templates',
// },
// output: {
// path: './',
// filename: 'handlebars.bundle.js',
// minify: false,
// },
// options: {
// verbose: true,
// },
// };
/* Start the bundler in watch mode (run as background task in production) */
handlebars-watch &
/* In your Node.js application (e.g., app.js) */
// First, install the handlebars runtime library
// npm install --save handlebars
const Handlebars = require('handlebars');
// Load the generated bundle. This will populate Handlebars.templates and Handlebars.partials.
require('./handlebars.bundle.js');
// Assuming you have a template named 'kittens.hbs' in your 'templates' directory,
// and a partial 'nes/ted/kitty.hbs' in your 'partials' directory.
const templateData = { message: 'Hello from Handlebars!' };
const kittenHtml = Handlebars.templates.kittens(templateData);
const nestedPartialHtml = Handlebars.partials['nes/ted/kitty'](templateData);
console.log('Kitten Template Output:', kittenHtml);
console.log('Nested Partial Output:', nestedPartialHtml);
// Example of using a custom helper (assuming 'capitalize' helper is defined in helpers/capitalize.js)
// Handlebars.registerHelper('capitalize', (context, options) => { /* ... */ });
// const capitalizedMessage = Handlebars.helpers.capitalize('my message'); // Direct helper call
handlebars --version
Errors
Common errors & fixes
ReferenceError: Handlebars is not defined
The main Handlebars.js library was not loaded before the `handlebars.bundle.js` file, which expects `Handlebars` to be globally available or a pre-imported CommonJS module.
fixFor Node.js, ensure `const Handlebars = require('handlebars');` is executed before `require('./handlebars.bundle.js');`. For browsers, include `<script src="path/to/handlebars.js"></script>` before the bundle script. Error: ENOENT: no such file or directory, stat 'handlebars.config.js'
The `handlebars-watch` or `handlebars-init` command was run in a directory where `handlebars.config.js` does not exist.
fixNavigate to the project's root directory or the directory containing your `handlebars.config.js` file. If it doesn't exist, run `handlebars-init` to create one.
TypeError: Handlebars.templates.myTemplate is not a function
Either the template file 'myTemplate.hbs' is missing from the configured `entry.templates` directory, or there's a typo in the template name when trying to access it via `Handlebars.templates`.
fixVerify that your template files exist in the `entry.templates` path specified in `handlebars.config.js` and that the filename (without extension) exactly matches the property you're trying to access on `Handlebars.templates`.
command not found: handlebars-init
The `ya-handlebars-bundler` package, which provides the `handlebars-init` and `handlebars-watch` commands, was not installed globally or is not in your system's PATH.
fixInstall the package globally using `npm install -g ya-handlebars-bundler` or ensure your local `node_modules/.bin` directory is in your PATH.
Audit
Dependencies
handlebarsrequiredThis bundler precompiles Handlebars templates, but the Handlebars.js runtime library itself (or the full Handlebars library) must be included separately in your application for the bundled templates to function. It is a critical runtime dependency.