vite-plugin-handlebars

2.0.3 verified Mon Apr 27 auth: no javascript

Vite plugin to preprocess HTML files with Handlebars templates during development and build. Current stable version 2.0.3 supports Vite 5, 6, 7, and 8. It injects context data, partials, and helpers into HTML files via `?handlebars` query or default HTML processing. Differentiates from generic Vite HTML transforms by providing Handlebars-specific integration with low configuration overhead. Requires Vite ≥5.

Common errors

error Error: Cannot find module 'vite-plugin-handlebars' ↓

cause Package not installed or mismatched Vite version.

fix

Run npm install vite-plugin-handlebars@latest and ensure Vite >=5.

error Error: The 'context' option must be an object ↓

cause Passed non-object (e.g., array, string) as context.

fix

Provide an object: context: { key: 'value' }.

error Error: Missing partial 'header' ↓

cause Partial path incorrect or file missing.

fix

Check that partial file exists at the given path relative to project root.

error Error: Handlebars compilation failed: ... ↓

cause Invalid Handlebars syntax in template or partial.

fix

Review template syntax; test with Handlebars standalone.

error Error: This plugin requires Vite >=5 ↓

cause Using Vite 4 or older.

fix

Upgrade Vite or install previous major version: npm install vite-plugin-handlebars@1.

Warnings

breaking vite-plugin-handlebars v2.0.0 dropped support for Vite 4; requires Vite ^5.0.0. ↓

fix Upgrade Vite to ^5.0.0 or stay on vite-plugin-handlebars v1.x.

breaking vite-plugin-handlebars v2.0.0 changed plugin export from default to named? Actually default export remains; verify import path. ↓

fix Use default import: `import handlebars from 'vite-plugin-handlebars'`.

gotcha Partial paths in `partials` option are resolved relative to the project root, not the partials directory; common misconfiguration. ↓

fix Use absolute paths or paths relative to process.cwd(), typically root of Vite project.

gotcha Context object is passed directly to Handlebars template; avoid passing functions or complex objects that may break serialization. ↓

fix Ensure context data is serializable (plain objects, arrays, strings, numbers).

deprecated Option `helpers` as object mapping was deprecated in v1.x; use function or object with explicit names. ↓

fix Pass helpers as an object where keys are helper names, values are helper functions.

Install

npm install vite-plugin-handlebars

yarn add vite-plugin-handlebars

pnpm add vite-plugin-handlebars

Imports

vitePluginHandlebars

wrong

const vitePluginHandlebars = require('vite-plugin-handlebars')

correct

import vitePluginHandlebars from 'vite-plugin-handlebars'

Default ES export; CJS require may fail if package is ESM-only (check package.json).

default

wrong

import { vitePluginHandlebars } from 'vite-plugin-handlebars'

correct

import vitePluginHandlebars from 'vite-plugin-handlebars'

Named import does not exist; use default import for the plugin function.

HandlebarsPluginOptions
```
import type { HandlebarsPluginOptions } from 'vite-plugin-handlebars'
```
TypeScript users can import the options interface for type safety.

Quickstart

Configures Vite with Handlebars plugin, providing context data, partials, helpers, and compile options.

import { defineConfig } from 'vite';
import handlebars from 'vite-plugin-handlebars';

export default defineConfig({
  plugins: [
    handlebars({
      context: {
        title: 'My App',
        items: ['a', 'b', 'c'],
      },
      partials: {
        header: 'src/partials/header.hbs',
      },
      helpers: {
        uppercase: (str) => str.toUpperCase(),
      },
      compileOptions: {
        preventIndent: true,
      },
    }),
  ],
});