rollup-plugin-handlebars-precompiler

1.0.2 verified Mon Apr 27 auth: no javascript

Rollup plugin that precompiles Handlebars templates into ES modules. Version 1.0.2 requires Node >=18 and Handlebars as a peer dependency. Generates ESM-only modules with TypeScript support, automatic partial detection, source maps, and convenient DOM integration via exported RawTemplate and Template functions. Unlike other Handlebars rollup plugins, it outputs DocumentFragment-ready modules with type definitions.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/rollup-plugin-handlebars-precompiler/dist/index.js from /path/to/rollup.config.js not supported. ↓

cause Attempting to use CommonJS require to load the ESM-only plugin.

fix

Change require() to import and ensure rollup.config.js uses ESM (e.g., rename to .mjs or set type: module in package.json).

error Error: Cannot find module 'handlebars' ↓

cause Handlebars is not installed as a project dependency.

fix

Run 'npm install handlebars' or 'pnpm add handlebars' in your project.

error Cannot find module './template.hbs' or its corresponding type declarations. ↓

cause TypeScript does not recognize .hbs imports; missing module declaration.

fix

Add a global type declaration: declare module '*.hbs' { import type { TemplateFunction } from 'rollup-plugin-handlebars-precompiler'; const tmpl: TemplateFunction; export default tmpl; export const RawTemplate: (context?: any, options?: any) => string; }

Warnings

breaking Package requires Node >=18 and ESM-only — no CommonJS support. ↓

fix Use Node 18+ and import via ESM syntax only.

gotcha Handlebars must be installed as a direct dependency of your project, not just this plugin. ↓

fix Run 'npm install handlebars' or 'pnpm add handlebars' in your project.

gotcha Generated modules use the Handlebars runtime from 'node_modules/handlebars/lib/handlebars.runtime.js' — ensure it is bundled. ↓

fix Make sure your bundler resolves the runtime; it is included automatically if rollup processes node_modules.

deprecated The plugin may not handle all Handlebars features; test partials and helpers thoroughly. ↓

fix Validate template compilation with the plugin's specific configuration for partials and helpers.

Install

npm install rollup-plugin-handlebars-precompiler

yarn add rollup-plugin-handlebars-precompiler

pnpm add rollup-plugin-handlebars-precompiler

Imports

rollup-plugin-handlebars-precompiler

wrong

const handlebarsPrecompiler = require('rollup-plugin-handlebars-precompiler')

correct

import handlebarsPrecompiler from 'rollup-plugin-handlebars-precompiler'

Package is ESM-only; CommonJS require will fail. Use default import only.

Template

wrong

import { Template } from './template.hbs'

correct

import Template, { RawTemplate } from './template.hbs'

Default export is the Template function; RawTemplate is a named export.

RawTemplate
wrong
```
import RawTemplate from './template.hbs'
```
correct
```
import { RawTemplate } from './template.hbs'
```
RawTemplate is not the default export; must use named import syntax.

Quickstart

Shows rollup config with plugin setup and usage of imported Handlebars template to append a DocumentFragment to the DOM.

// rollup.config.js
import handlebarsPrecompiler from 'rollup-plugin-handlebars-precompiler'

export default {
  input: 'src/main.js',
  output: { dir: 'dist', format: 'esm' },
  plugins: [
    handlebarsPrecompiler({
      // Include handlebars helpers from a specific file
      helpers: 'src/helpers/**/*.js',
      // enable source maps
      sourceMap: true
    })
  ]
}

// src/main.js
import Template from './component.hbs'

const app = document.getElementById('app')
const context = { message: 'Hello' }
app.appendChild(Template(context))