Handlebars Transpiler

1.0.3 verified Fri May 01 auth: no javascript

Handlebars Transpiler is a Node.js module for compiling Handlebars templates along with partials, JSON data, and custom helpers into static HTML files. Version 1.0.3 is the latest stable release; the package is actively maintained with a focus on simplicity for generating static sites from Handlebars templates. It differentiates itself from other build tools by being a lightweight, zero-config CLI and programmatic API specifically for Handlebars, with no dependency on larger frameworks like Gulp or Grunt. It supports custom output paths and partials registration. It is not suitable for dynamic rendering or runtime caching.

Common errors

error Error: Cannot find module 'handlebars' ↓

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

fix

Run 'npm install handlebars' in your project.

error TypeError: template must be a string ↓

cause The 'template' option provided is not a string (e.g., object or undefined).

fix

Ensure the 'template' option is a valid file path string.

error Error: ENOENT: no such file or directory, open 'data.json' ↓

cause The 'data' file path is incorrect or the file does not exist.

fix

Verify the path to your JSON data file is correct relative to the working directory.

Warnings

gotcha The 'partials' option expects an array of file paths, not Handlebars partial registration strings. ↓

fix Provide absolute or relative paths to .hbs files; partials are automatically registered with their filename (without extension).

deprecated The 'compile' function is deprecated in favor of 'transpile'. ↓

fix Replace any call to 'compile' with 'transpile' using the same API.

gotcha The 'data' option only accepts a JSON file path; inline data objects are not supported. ↓

fix Create a separate JSON file and pass its path as the 'data' option.

breaking Version 1.0.0 changed the exported API from a default function to named exports ('transpile', 'transpileSync'). ↓

fix Update imports to use named exports: import { transpile } from 'handlebars-transpiler'.

Install

npm install handlebars-transpiler

yarn add handlebars-transpiler

pnpm add handlebars-transpiler

Imports

transpile

wrong

const { transpile } = require('handlebars-transpiler')

correct

import { transpile } from 'handlebars-transpiler'

ESM default export only; named import 'transpile' is the expected API.

transpileSync

wrong

import transpileSync from 'handlebars-transpiler'

correct

import { transpileSync } from 'handlebars-transpiler'

Named export for synchronous transpilation; do not use default import.

TranspilerOptions

wrong

import { TranspilerOptions } from 'handlebars-transpiler'

correct

import type { TranspilerOptions } from 'handlebars-transpiler'

TypeScript type export; use 'import type' to avoid runtime inclusion.

Quickstart

Demonstrates transpiling a Handlebars template with data, partials, and a custom helper to a static HTML file.

import { transpile } from 'handlebars-transpiler';

const config = {
  template: 'template.hbs',
  data: 'data.json',
  partials: ['partials/header.hbs', 'partials/footer.hbs'],
  helpers: {
    uppercase: (str) => str.toUpperCase()
  },
  output: 'index.html'
};

transpile(config).then(() => {
  console.log('Static HTML generated successfully');
}).catch(err => {
  console.error('Transpilation failed:', err);
});