vite-plugin-page-reload

0.2.3 verified Mon Apr 27 auth: no javascript

Automatically reload the page when watched files change during development with Vite. Current stable version is 0.2.3. Release cadence is irregular, with updates primarily to support new Vite major versions (v5, v6, v7, v8). Key differentiator from alternatives (like vite-plugin-live-reload or vite-plugin-full-reload) is the inclusion of a debounce function and a configurable delay. Ships TypeScript types. Commonly used in Shopify theme development setups.

Common errors

error Cannot find module 'vite-plugin-page-reload' or its corresponding type declarations. ↓

cause Package not installed or TypeScript cannot resolve types.

fix

Run npm install -D vite-plugin-page-reload and ensure tsconfig includes node_modules resolution.

error ERR_REQUIRE_ESM: require() of ES Module ... not supported. ↓

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

fix

Change to import statement or use dynamic import(). Ensure your project is ESM by adding "type": "module" to package.json.

error TypeError: pageReload is not a function ↓

cause Using named import instead of default import.

fix

Change import { pageReload } to import pageReload.

error The requested module 'vite-plugin-page-reload' does not provide an export named 'PageReloadOptions' ↓

cause Importing a type as a value.

fix

Use import type { PageReloadOptions } from 'vite-plugin-page-reload'

Warnings

breaking Default export changed from object to function in v0.2.0 ↓

fix Update import from `import { pageReload }` to `import pageReload`

breaking Vite 4 support dropped in v0.2.2 ↓

fix Use v0.2.1 if you need Vite 4 support

gotcha Paths are relative to root option, default process.cwd(). Glob patterns supported but not documented. ↓

fix Use absolute paths or ensure root matches your project structure

gotcha Setting `always: false` may cause inconsistent reloads when multiple files change simultaneously ↓

fix Keep `always: true` (default) to ensure reload on any watched file change

deprecated Options `watchOptions` and `ignore` have been removed in v0.2.0. Use `always` and `paths` instead. ↓

fix Remove `watchOptions` and `ignore`; configure via `always` and `paths`

Install

npm install vite-plugin-page-reload

yarn add vite-plugin-page-reload

pnpm add vite-plugin-page-reload

Imports

pageReload

wrong

const pageReload = require('vite-plugin-page-reload')

correct

import pageReload from 'vite-plugin-page-reload'

Default export; ESM-only since v0.2.0. CommonJS require will fail.

PageReloadOptions

wrong

import { PageReloadOptions } from 'vite-plugin-page-reload'

correct

import type { PageReloadOptions } from 'vite-plugin-page-reload'

Type export for TypeScript users; do not use value import.

PageReloadPlugin

wrong

import { PageReloadPlugin } from 'vite-plugin-page-reload'

correct

import type { PageReloadPlugin } from 'vite-plugin-page-reload'

Type export for the plugin type; value import will be undefined.

Quickstart

Configure Vite to reload the browser when /tmp/theme.update is modified, with a 50ms delay and logging enabled.

// vite.config.js
import { defineConfig } from 'vite'
import pageReload from 'vite-plugin-page-reload'

export default defineConfig({
  plugins: [
    pageReload('/tmp/theme.update', {
      always: true,
      delay: 50,
      log: true
    })
  ]
})