{"id":27518,"library":"vite-plugin-handlebars","title":"vite-plugin-handlebars","description":"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.","status":"active","version":"2.0.3","language":"javascript","source_language":"en","source_url":"git@github.com:alexlafroscia/vite-plugin-handlebars","tags":["javascript"],"install":[{"cmd":"npm install vite-plugin-handlebars","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-handlebars","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-handlebars","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; require Vite ≥5","package":"vite","optional":false}],"imports":[{"note":"Default ES export; CJS require may fail if package is ESM-only (check package.json).","wrong":"const vitePluginHandlebars = require('vite-plugin-handlebars')","symbol":"vitePluginHandlebars","correct":"import vitePluginHandlebars from 'vite-plugin-handlebars'"},{"note":"Named import does not exist; use default import for the plugin function.","wrong":"import { vitePluginHandlebars } from 'vite-plugin-handlebars'","symbol":"default","correct":"import vitePluginHandlebars from 'vite-plugin-handlebars'"},{"note":"TypeScript users can import the options interface for type safety.","symbol":"HandlebarsPluginOptions","correct":"import type { HandlebarsPluginOptions } from 'vite-plugin-handlebars'"}],"quickstart":{"code":"import { defineConfig } from 'vite';\nimport handlebars from 'vite-plugin-handlebars';\n\nexport default defineConfig({\n  plugins: [\n    handlebars({\n      context: {\n        title: 'My App',\n        items: ['a', 'b', 'c'],\n      },\n      partials: {\n        header: 'src/partials/header.hbs',\n      },\n      helpers: {\n        uppercase: (str) => str.toUpperCase(),\n      },\n      compileOptions: {\n        preventIndent: true,\n      },\n    }),\n  ],\n});","lang":"typescript","description":"Configures Vite with Handlebars plugin, providing context data, partials, helpers, and compile options."},"warnings":[{"fix":"Upgrade Vite to ^5.0.0 or stay on vite-plugin-handlebars v1.x.","message":"vite-plugin-handlebars v2.0.0 dropped support for Vite 4; requires Vite ^5.0.0.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use default import: `import handlebars from 'vite-plugin-handlebars'`.","message":"vite-plugin-handlebars v2.0.0 changed plugin export from default to named? Actually default export remains; verify import path.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use absolute paths or paths relative to process.cwd(), typically root of Vite project.","message":"Partial paths in `partials` option are resolved relative to the project root, not the partials directory; common misconfiguration.","severity":"gotcha","affected_versions":"*"},{"fix":"Ensure context data is serializable (plain objects, arrays, strings, numbers).","message":"Context object is passed directly to Handlebars template; avoid passing functions or complex objects that may break serialization.","severity":"gotcha","affected_versions":"*"},{"fix":"Pass helpers as an object where keys are helper names, values are helper functions.","message":"Option `helpers` as object mapping was deprecated in v1.x; use function or object with explicit names.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Run `npm install vite-plugin-handlebars@latest` and ensure Vite >=5.","cause":"Package not installed or mismatched Vite version.","error":"Error: Cannot find module 'vite-plugin-handlebars'"},{"fix":"Provide an object: `context: { key: 'value' }`.","cause":"Passed non-object (e.g., array, string) as context.","error":"Error: The 'context' option must be an object"},{"fix":"Check that partial file exists at the given path relative to project root.","cause":"Partial path incorrect or file missing.","error":"Error: Missing partial 'header'"},{"fix":"Review template syntax; test with Handlebars standalone.","cause":"Invalid Handlebars syntax in template or partial.","error":"Error: Handlebars compilation failed: ..."},{"fix":"Upgrade Vite or install previous major version: `npm install vite-plugin-handlebars@1`.","cause":"Using Vite 4 or older.","error":"Error: This plugin requires Vite >=5"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}