Registry / web-framework / vite-plugin-handlebars

vite-plugin-handlebars

library2.0.3jsnpmunverified

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.

web-framework

npm install vite-plugin-handlebars

package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-HANDLE

vite-plugin-handlebars

web-frameworkjavascriptv2.0.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

vitePluginHandlebars

✓ import vitePluginHandlebars from 'vite-plugin-handlebars'

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

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

default

✓ import vitePluginHandlebars from 'vite-plugin-handlebars'

✗ 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.

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, }, }), ], });

Debug

Known issues

breakingvite-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.

affects: >=2.0.0

breakingvite-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'`.

affects: >=2.0.0

gotchaPartial 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.

affects: *

gotchaContext 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).

affects: *

deprecatedOption `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.

affects: >=1.0.0

Errors

Common errors & fixes

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

Package not installed or mismatched Vite version.

fix

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

Error: The 'context' option must be an object

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

fix

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

Error: Missing partial 'header'

Partial path incorrect or file missing.

fix

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

Error: Handlebars compilation failed: ...

Invalid Handlebars syntax in template or partial.

fix

Review template syntax; test with Handlebars standalone.

Error: This plugin requires Vite >=5

Using Vite 4 or older.

fix

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

Upgrade

Version history

2.0.3latest on npm

Audit

Dependencies

viterequiredPeer dependency; require Vite ≥5

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/vite-plugin-handlebars ↗