{"id":22641,"library":"vite-plugin-drupal-twig-hmr","title":"vite-plugin-drupal-twig-hmr","description":"A Vite plugin that enables Hot Module Replacement (HMR) for Drupal Twig templates and Single-Directory Components. Current stable version is 1.0.1, released on a low cadence. It uses Vite's HMR API and Drupal's Twig debug mode to fetch updated HTML and perform DOM replacements when a .twig file changes. Limited to theme suggestions and does not support TypeScript or automated testing. Differentiates from other Drupal build tools by providing instant template reloads without full page refresh, but requires a compatible Vite-Drupal setup (e.g., via the Vite module) and a virtual module script injected into the backend.","status":"active","version":"1.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/yannickoo/vite-plugin-drupal-twig-hmr","tags":["javascript","vite-plugin","drupal","hmr"],"install":[{"cmd":"npm install vite-plugin-drupal-twig-hmr","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-drupal-twig-hmr","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-drupal-twig-hmr","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM-only; CommonJS require is not supported.","wrong":"const viteDrupalTwigHMR = require('vite-plugin-drupal-twig-hmr')","symbol":"viteDrupalTwigHMR (default export)","correct":"import viteDrupalTwigHMR from 'vite-plugin-drupal-twig-hmr'"},{"note":"Type import only; PluginOptions is a TypeScript type, not a runtime value.","wrong":"import { PluginOptions } from 'vite-plugin-drupal-twig-hmr'","symbol":"PluginOptions (type)","correct":"import type { PluginOptions } from 'vite-plugin-drupal-twig-hmr'"},{"note":"The virtual module is requested via a script tag in the backend, not imported in frontend code.","wrong":"import something from '/@vite-plugin-drupal-template-hmr'","symbol":"Virtual module URL","correct":"// In your Drupal template: <script src=\"localhost:5173/@vite-plugin-drupal-template-hmr\" type=\"module\"></script>"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport viteDrupalTwigHMR from 'vite-plugin-drupal-twig-hmr';\n\nexport default defineConfig({\n  server: {\n    port: 5173, // must match Drupal script src\n  },\n  plugins: [\n    viteDrupalTwigHMR({\n      // templateBase: '/path/to/drupal/root' // optional\n    }),\n  ],\n});","lang":"typescript","description":"Basic setup of the plugin in a Vite config file, showing import, server port, and plugin usage with optional templateBase option."},"warnings":[{"fix":"No action needed; this is by design. Ensure you only rely on the plugin in development.","message":"Plugin only active during Vite dev server; production builds will not include any HMR functionality.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Restructure templates to be theme suggestions where possible. For included templates, a full page reload may be needed.","message":"Twig HMR only works for templates that are directly referenced as a theme suggestion; templates included via include/embed may not update correctly.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Enable debug mode in Drupal's services.yml or settings.local.php.","message":"Requires Drupal Twig debug mode enabled (twig.config: debug: true) to insert HTML comments used for DOM replacement.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Add <script src='http://localhost:5173/@vite-plugin-drupal-template-hmr' type='module'></script> to your HTML or page template.","message":"The virtual module must be manually added as a script tag in your Drupal template; it is not automatically injected.","severity":"gotcha","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-drupal-twig-hmr --save-dev`","cause":"Package not installed or node_modules missing.","error":"Error: [vite] Internal server error: Cannot find module 'vite-plugin-drupal-twig-hmr'"},{"fix":"Use `import viteDrupalTwigHMR from 'vite-plugin-drupal-twig-hmr'` in an ESM context (type: module in package.json or .mjs extension).","cause":"Using CommonJS require() on an ESM-only package.","error":"TypeError: viteDrupalTwigHMR is not a function"},{"fix":"Ensure Vite dev server is running on the expected port (e.g., 5173) and the script src matches (e.g., http://localhost:5173/@vite-plugin-drupal-template-hmr).","cause":"Vite dev server not running or port mismatch, or script src points to wrong URL.","error":"Uncaught TypeError: Failed to fetch dynamically imported module: http://localhost:5173/@vite-plugin-drupal-template-hmr"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}