Vite Plugin Live Reload

3.1.0 verified Mon Apr 27 auth: no javascript

vite-plugin-live-reload is a simple Vite plugin that triggers a full page reload when watched files change. Current stable version is 3.1.0, with a release cadence of occasional minor/patch updates. It uses chokidar under the hood and supports glob patterns, multiple paths, a custom root, and an alwaysReload option. Unlike Vite's built-in HMR, this plugin targets backend-driven projects (e.g., Kirby CMS, PHP, Rails) where file changes on the server side need to trigger a browser reload. It has zero runtime dependencies beyond Vite (peer dep vite ^4 || ^5 || ^6 || ^7 || ^8) and ships TypeScript definitions.

Common errors

error Uncaught Error: [vite] The "path" argument must be of type string. Received undefined ↓

cause liveReload() called without any path argument or with undefined.

fix

Pass at least one glob pattern string or array: liveReload('**/*.php').

error Error: Cannot find module 'vite' ↓

cause Vite is not installed or peer dependency not met.

fix

Run npm install vite --save-dev.

error TypeError: liveReload is not a function ↓

cause Importing incorrectly, e.g., named import when using default import or vice versa.

fix

Use import liveReload from 'vite-plugin-live-reload' (default) or import { viteLiveReload } from 'vite-plugin-live-reload' (named).

error [vite] server is not ready yet - liveReload will start on first request ↓

cause The plugin is loaded but the server hasn't started; typically harmless informational message.

fix

No action needed; it's normal behavior.

Warnings

breaking v3.0.0 changed peer dependency to Vite 3+; incompatible with Vite 2. ↓

fix Upgrade to Vite >=3 or stick with v2.x line (v2.1.0).

gotcha Paths are relative to Vite's root by default, not process.cwd(). ↓

fix Use the 'root' option to set a custom root directory: liveReload('path', { root: process.cwd() }).

gotcha The plugin does not work with Vite's built-in HMR; it triggers a full page reload, not hot module replacement. ↓

fix Use only for backend file watchers; do not expect HMR-like behavior.

gotcha alwaysReload option causes reload even if browser is not on the modified HTML page; may cause unwanted reloads. ↓

fix Use with caution; only enable when needed for specific workflows.

deprecated v2.x required importing as { liveReload } named export; default export added in v3.0.1. ↓

fix Use default import: import liveReload from 'vite-plugin-live-reload' (or named export still works).

Install

npm install vite-plugin-live-reload

yarn add vite-plugin-live-reload

pnpm add vite-plugin-live-reload

Imports

liveReload
wrong
```
import { liveReload } from 'vite-plugin-live-reload'
```
correct
```
import liveReload from 'vite-plugin-live-reload'
```
Default export was added in v3.0.1; pre-v3 it was a named export. The named export still exists as an alias.

viteLiveReload

wrong

import viteLiveReload from 'vite-plugin-live-reload'

correct

import { viteLiveReload } from 'vite-plugin-live-reload'

Named export for those who prefer named imports. Equivalent to default.

Config
```
import type { Config } from 'vite-plugin-live-reload'
```
Config type interface for options. Available since v3.x with TypeScript support.

Quickstart

Configures Vite to reload the browser when PHP or Twig files change using glob patterns and alwaysReload option.

// vite.config.js
import liveReload from 'vite-plugin-live-reload'

export default {
  root: './',
  plugins: [
    liveReload(['../server/**/*.php', '../views/**/*.twig'], { alwaysReload: true }),
  ],
}