Vite Plugin Web Components HMR

0.1.3 verified Mon Apr 27 auth: no javascript

A Vite plugin enabling hot module replacement (HMR) for web components, primarily designed for LitElement and similar libraries. Current stable version is 0.1.3, with low release cadence. It is a fork of @open-wc/dev-server-hmr adapted for Vite's plugin system. Key differentiator: seamless HMR for custom elements in Vite projects without additional configuration. Supports TypeScript, configurable inclusion patterns, and presets for popular libraries (Lit, FAST, etc.). Primarily used with Vite 2+.

Common errors

error Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'vite-plugin-web-components-hmr' ↓

cause Package not installed or not in node_modules.

fix

Run npm install -D vite-plugin-web-components-hmr or equivalent.

error TypeError: hmrPlugin is not a function ↓

cause Using default import instead of named import.

fix

Use import { hmrPlugin } from 'vite-plugin-web-components-hmr'.

error ViteError: Cannot find module 'vite-plugin-web-components-hmr' ... Did you mean to import 'vite-plugin-web-components-hmr'? ↓

cause Plugin not included in Vite's optimizeDeps or not installed.

fix

Ensure the package is installed. Add to optimizeDeps.include if necessary.

error Invalid presets argument: Expected an array. ↓

cause Passing a single preset object without array brackets.

fix

Wrap presets in an array: presets: [presets.lit].

Warnings

breaking Requires Vite >=2. Will fail to resolve plugin if Vite version is older. ↓

fix Upgrade Vite to version 2 or higher.

gotcha Plugin is ESM-only. Cannot be used with CommonJS require(). ↓

fix Use import syntax in an ES module context.

deprecated Options are directly from @open-wc/dev-server-hmr, which may deprecate or change. Check compatibility. ↓

fix Refer to @open-wc/dev-server-hmr documentation for available options.

gotcha include patterns must match file paths relative to project root. Wrong glob can cause no HMR. ↓

fix Ensure include globs cover all component files, e.g., 'src/components/**/*.ts'.

deprecated Presets may not cover all web component libraries; custom presets may be needed. ↓

fix Check preset definitions; can create custom presets using the same format.

Install

npm install vite-plugin-web-components-hmr

yarn add vite-plugin-web-components-hmr

pnpm add vite-plugin-web-components-hmr

Imports

hmrPlugin

wrong

const hmrPlugin = require('vite-plugin-web-components-hmr')

correct

import { hmrPlugin } from 'vite-plugin-web-components-hmr'

ESM-only package, cannot use CommonJS require().

presets

wrong

import { presets } from 'vite-plugin-web-components-hmr/presets'

correct

import { presets } from 'vite-plugin-web-components-hmr'

presets is a named export from the main entry, not a subpath.

default import

wrong

No common wrong pattern, but default export is not documented; use named imports.

correct

import vitePluginWcHmr from 'vite-plugin-web-components-hmr'

Package has no default export; use named imports { hmrPlugin }.

Quickstart

Basic setup with Lit preset. Add plugin to Vite config to enable HMR for components matching the include pattern.

// vite.config.ts
import { defineConfig } from 'vite';
import { hmrPlugin, presets } from 'vite-plugin-web-components-hmr';

export default defineConfig({
  plugins: [
    hmrPlugin({
      include: ['./src/**/*.ts'],
      presets: [presets.lit],
    }),
  ],
});