vite-plugin-drupal-twig-hmr

1.0.1 verified Mon Apr 27 auth: no javascript

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.

Common errors

error Error: [vite] Internal server error: Cannot find module 'vite-plugin-drupal-twig-hmr' ↓

cause Package not installed or node_modules missing.

fix

Run npm install vite-plugin-drupal-twig-hmr --save-dev

error TypeError: viteDrupalTwigHMR is not a function ↓

cause Using CommonJS require() on an ESM-only package.

fix

Use import viteDrupalTwigHMR from 'vite-plugin-drupal-twig-hmr' in an ESM context (type: module in package.json or .mjs extension).

error Uncaught TypeError: Failed to fetch dynamically imported module: http://localhost:5173/@vite-plugin-drupal-template-hmr ↓

cause Vite dev server not running or port mismatch, or script src points to wrong URL.

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

Warnings

gotcha Plugin only active during Vite dev server; production builds will not include any HMR functionality. ↓

fix No action needed; this is by design. Ensure you only rely on the plugin in development.

gotcha Twig HMR only works for templates that are directly referenced as a theme suggestion; templates included via include/embed may not update correctly. ↓

fix Restructure templates to be theme suggestions where possible. For included templates, a full page reload may be needed.

gotcha Requires Drupal Twig debug mode enabled (twig.config: debug: true) to insert HTML comments used for DOM replacement. ↓

fix Enable debug mode in Drupal's services.yml or settings.local.php.

gotcha The virtual module must be manually added as a script tag in your Drupal template; it is not automatically injected. ↓

fix Add <script src='http://localhost:5173/@vite-plugin-drupal-template-hmr' type='module'></script> to your HTML or page template.

Install

npm install vite-plugin-drupal-twig-hmr

yarn add vite-plugin-drupal-twig-hmr

pnpm add vite-plugin-drupal-twig-hmr

Imports

viteDrupalTwigHMR (default export)

wrong

const viteDrupalTwigHMR = require('vite-plugin-drupal-twig-hmr')

correct

import viteDrupalTwigHMR from 'vite-plugin-drupal-twig-hmr'

ESM-only; CommonJS require is not supported.

PluginOptions (type)

wrong

import { PluginOptions } from 'vite-plugin-drupal-twig-hmr'

correct

import type { PluginOptions } from 'vite-plugin-drupal-twig-hmr'

Type import only; PluginOptions is a TypeScript type, not a runtime value.

Virtual module URL

wrong

import something from '/@vite-plugin-drupal-template-hmr'

correct

// In your Drupal template: <script src="localhost:5173/@vite-plugin-drupal-template-hmr" type="module"></script>

The virtual module is requested via a script tag in the backend, not imported in frontend code.

Quickstart

Basic setup of the plugin in a Vite config file, showing import, server port, and plugin usage with optional templateBase option.

// vite.config.ts
import { defineConfig } from 'vite';
import viteDrupalTwigHMR from 'vite-plugin-drupal-twig-hmr';

export default defineConfig({
  server: {
    port: 5173, // must match Drupal script src
  },
  plugins: [
    viteDrupalTwigHMR({
      // templateBase: '/path/to/drupal/root' // optional
    }),
  ],
});