@magic-spells/vite-plugin-live-reload

A small Vite dev-server plugin for libraries whose demo doubles as a static-deployed site — the kind of project where the same index.html runs on localhost:3000 during dev AND gets served straight off GitHub Pages, with the library loaded via pre-built <script> and <link> tags.

In that setup, Vite's HMR doesn't know about the externally-built bundles, so the browser never reloads when your library rebuilds. And worse: Vite caches a JS-wrapped version of any CSS file it sees (for its own HMR machinery) and never invalidates that cache for files outside its module graph — so even a manual reload serves stale styles until you restart the dev server.

This plugin fixes both:

1. Watches the dist directory with fs.watch (recursive) and broadcasts full-reload over Vite's existing HMR WebSocket when files change.
2. Adds a middleware that intercepts ${urlPrefix}*.css requests before Vite's CSS pipeline and streams the raw file with Content-Type: text/css, Cache-Control: no-store.

Install

npm install --save-dev @magic-spells/vite-plugin-live-reload

Peer dependency: vite >=5.

Usage

import { createServer } from 'vite';
import liveReload from '@magic-spells/vite-plugin-live-reload';

const server = await createServer({
  root: 'demo',
  plugins: [liveReload('demo/dist')],
});
await server.listen();

The string shorthand sets distDir and derives sensible defaults. For more control:

liveReload({
  distDir: 'demo/dist',
  urlPrefix: '/dist/',
  extensions: ['.css'],
  debounce: 250,
});

Options

| Option | Default | Description | | ------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------- | | distDir | required | Directory to watch and serve raw from. Resolved relative to process.cwd(). | | urlPrefix | '/' + basename(distDir) + '/' | URL path that maps to distDir. For distDir: 'demo/dist' this defaults to /dist/. | | extensions | ['.css'] | File extensions served raw by the middleware. Only files matching these extensions bypass Vite. | | debounce | 250 | Debounce window (ms) for coalescing burst writes from parallel build pipelines into one reload. |

When you DON'T need this

If your demo imports your library's source directly through Vite's pipeline:

<script type="module" src="/src/my-library.js"></script>

…then you already get true HMR for free — Vite's module graph picks up source changes and pushes granular updates without a full reload. You don't need this plugin.

This plugin is specifically for the case where your demo loads pre-built bundles because the same HTML needs to work as a static deployment. If you're not deploying the demo as a static site, the idiomatic Vite pattern (above) gives you a strictly better dev experience.

How it works

The plugin registers a single configureServer hook. Inside that hook, two things happen:

1. Middleware (server.middlewares.use(...)) — Vite's middleware chain processes requests in order. By registering ours synchronously inside configureServer, it runs before Vite's internal CSS transformer. For any URL that matches urlPrefix and ends in one of the configured extensions, we stream the raw file from disk and skip the rest of the chain. Everything else (HTML, JS, source maps, files outside the prefix) flows through Vite normally.

2. File watcher (fs.watch(distAbs, { recursive: true })) — Node's built-in recursive watcher uses FSEvents on macOS and ReadDirectoryChangesW on Windows (both native and efficient). On Linux it falls back to polling. When any file under distDir changes, we set a debounce timer; when the timer fires, we call server.hot.send({ type: 'full-reload', path: '*' }) to tell every connected browser to reload. The debounce coalesces the burst of writes that a multi-target rebuild produces (e.g. ESM + UMD + minified).

The plugin uses apply: 'serve', so it's a no-op in production builds — safe to leave in your config.

Why not vite-plugin-full-reload?

vite-plugin-full-reload handles the watch-and-reload piece (item #1 above) and is great if that's all you need. It doesn't fix the stale-CSS-cache issue (item #2), because that's a Vite-internal cache that only affects projects serving CSS via <link> to a directory Vite is also transforming. If you hit the symptom — "I reload the page but styles are still old until I restart the server" — that's the cache bug, and it needs the raw-serve middleware.

License

MIT