Registry / devops / vite-plugin-restart

vite-plugin-restart

library2.0.0jsnpmunverified

vite-plugin-restart is a Vite development server plugin that allows developers to define custom files or glob patterns whose changes trigger an automatic restart of the Vite server or a client-side full page reload. This eliminates the need for manual server restarts when modifying configuration files, database schemas, or other non-hot-reloadable assets, often replacing external watchers like `nodemon`. The package is currently stable at version `2.0.0` and typically releases updates to maintain compatibility with new Vite major versions and introduce features or bug fixes. A key differentiator introduced in v2.0.0 is content-based change detection, which, by default, prevents unnecessary restarts caused by file metadata changes or infinite loops when watching auto-generated files. It also offers a `delay` option to debounce restart triggers.

devops

npm install vite-plugin-restart

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-RESTAR

vite-plugin-restart

devopsjavascriptv2.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ViteRestart

✓ import ViteRestart from 'vite-plugin-restart'

✗ import { ViteRestart } from 'vite-plugin-restart'

ViteRestart is a default export. The package is ESM-only since v0.4.0, so CommonJS `require()` is not supported.

ViteRestart

✓ import ViteRestart from 'vite-plugin-restart'

✗ const ViteRestart = require('vite-plugin-restart')

Since v0.4.0, the package is ESM-only (`type:module`). CommonJS `require()` will throw an error. Ensure your Vite config uses ESM syntax or is an `.mjs` file.

This quickstart demonstrates how to configure `vite-plugin-restart` in `vite.config.ts` to automatically restart the Vite development server when specified configuration files (like `my.config.ts`) change, or trigger a full client-side reload for other file types. It showcases the `restart`, `reload`, and `delay` options.

import { defineConfig } from 'vite'; import ViteRestart from 'vite-plugin-restart'; export default defineConfig({ plugins: [ ViteRestart({ restart: [ 'my.config.[jt]s', // Watches for changes in my.config.js or my.config.ts './path/to/schema/*.prisma', // Example: watch Prisma schema files ], reload: [ './public/**/*.html' // Example: full page reload for HTML changes ], delay: 750, // Debounce restarts by 750ms contentCheck: true, // Enabled by default since v2.0.0 }) ], });

Debug

Known issues

breakingThe plugin migrated to ESM (`type:module`) in version `0.4.0`. Projects still using CommonJS `require()` syntax for their Vite configuration will encounter errors.

fix

Ensure your `vite.config.js` is set up for ESM (e.g., using `import` statements, or renaming to `vite.config.mjs`).

affects: >=0.4.0

gotchaSince `v2.0.0`, `contentCheck` is enabled by default. This feature prevents infinite restart loops by only triggering a restart if the file's *content* actually changes, not just its metadata. While beneficial, if your workflow relies on restarts for non-content-based file updates (e.g., timestamp changes of empty files), you might need to explicitly set `contentCheck: false`.

fix

If specific edge cases require restarting on metadata-only changes, set `contentCheck: false` in the plugin options. Otherwise, no action is needed as this is the new default behavior.

affects: >=2.0.0

gotchaPrior to `v2.0.0` or when `contentCheck` is explicitly disabled, watching auto-generated files (like `.eslintrc-auto-import.json`) can lead to infinite server restart loops. The server restarts, the file regenerates, which triggers another restart.

fix

Ensure `contentCheck: true` (default since `v2.0.0`) or carefully select files that do not cause circular dependencies for restarts. Consider using the `delay` option to debounce restarts for slower systems.

affects: <2.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module C:\path\to\node_modules\vite-plugin-restart\dist\index.mjs not supported.

Attempting to use `require()` to import `vite-plugin-restart` in a CommonJS context, but the package is ESM-only since v0.4.0.

fix

Update your `vite.config.js` to use ESM `import` statements. If you're encountering issues with your environment's ESM support, consider renaming `vite.config.js` to `vite.config.mjs`.

Vite server enters infinite restart loop after saving a file.

A watched file is being regenerated or modified by a process that is triggered by the Vite server restart itself, creating a feedback loop. This is common with auto-generated files or files whose modification timestamp changes without actual content changes.

fix

Ensure `contentCheck: true` is enabled (it's the default since `v2.0.0`). This feature only triggers restarts if file content changes. If the issue persists, carefully review your `restart` array to exclude files that are frequently rewritten or disable `contentCheck` and add a sufficiently large `delay`.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

viterequiredCore peer dependency for Vite plugin integration.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/antfu/vite-plugin-restart ↗

packagehttps://www.npmjs.com/package/vite-plugin-restart ↗