esbuild-handlebars

1.1.0 verified Fri May 01 auth: no javascript

An esbuild plugin for compiling Handlebars templates (.hbs, .handlebars) into JavaScript modules. Current stable version is 1.1.0. It resolves the 'Cannot read properties of undefined (reading call)' error common in other plugins, supports custom helpers/partials injection, and uses Handlebars precompilation for optimal performance. Key differentiators: fixes nested helper calls, integrates seamlessly with esbuild's build pipeline, and is lightweight with no extra runtime dependencies.

Common errors

error Cannot read properties of undefined (reading 'call') ↓

cause Using a version of the original plugin that doesn't handle nested helper calls correctly.

fix

Update to esbuild-handlebars v1.1.0, which resolves this issue. Install the latest version: npm install -D esbuild-handlebars@latest.

error Error: No matching loader for ".hbs" files ↓

cause The plugin is not registered correctly, or esbuild doesn't have a loader for .hbs files.

fix

Add the plugin to the 'plugins' array in your esbuild config: plugins: [require('esbuild-handlebars')(options)].

Warnings

gotcha The plugin only runs during esbuild's load phase; ensure your filter matches the file extensions you want to process. ↓

fix Set the filter option to a RegExp that matches your Handlebars file extensions, e.g., /\.(hbs|handlebars)$/i.

gotcha additionalHelpers and additionalPartials expect file paths (strings) pointing to JavaScript modules that export the helper/partial function. ↓

fix Use absolute or relative paths to .js files that export the helper/partial, not inline functions.

gotcha The plugin does not provide TypeScript type definitions; using it in a TypeScript project may require custom type declarations. ↓

fix Add a declaration file (e.g., 'esbuild-handlebars.d.ts') with: declare module 'esbuild-handlebars' { export default function hbsPlugin(options?: any): any; export const handlebarsPlugin: typeof hbsPlugin; }

Install

npm install esbuild-handlebars

yarn add esbuild-handlebars

pnpm add esbuild-handlebars

Imports

default (plugin factory)
wrong
```
const hbsPlugin = require('esbuild-handlebars')
```
correct
```
import hbsPlugin from 'esbuild-handlebars'
```
The package exports a default function that takes an options object. ESM import is the recommended way, but CJS require works in Node.js.
handlebarsPlugin (named export)
wrong
```
import handlebarsPlugin from 'esbuild-handlebars'
```
correct
```
import { handlebarsPlugin } from 'esbuild-handlebars'
```
The package also exports 'handlebarsPlugin' as a named export. Use named import if you prefer explicit naming.
TypeScript usage
wrong
```
import { hbsPlugin } from 'esbuild-handlebars'
```
correct
```
import hbsPlugin from 'esbuild-handlebars'
```
The package does not ship TypeScript types. You may need to declare a module or use @types/handlebars for type checking.

Quickstart

Shows basic usage: require the plugin, create options with a filter and optional helpers, then add to esbuild plugins list.

const esbuild = require('esbuild');
const hbsPlugin = require('esbuild-handlebars');

const hbsOptions = {
  filter: /\.(hbs|handlebars)$/i,
  additionalHelpers: {
    equal: require('path').join(__dirname, 'helper', 'template', 'equal')
  },
  precompileOptions: {}
};

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [require('esbuild-handlebars')(hbsOptions)],
}).catch(() => process.exit(1));