vite-plugin-watch

0.3.1 verified Mon Apr 27 auth: no javascript

A Vite plugin that runs shell commands automatically when files matching a glob pattern change. Version 0.3.1 is the latest stable release, with infrequent updates. It supports single or multiple commands, configurable debounce timeout, silent mode, and optional initial run on Vite start. Differentiates from other watch plugins by integrating with the Vite dev server lifecycle and supporting minimal configuration.

Common errors

error Unexpected token 'export' ↓

cause Using require() in a CommonJS file without proper destructuring or using ESM syntax in a CJS context.

fix

Use const { watch } = require('vite-plugin-watch') or switch to ESM.

error Cannot find module 'vite-plugin-watch' ↓

cause Package not installed or missing from package.json.

fix

Run npm i -D vite-plugin-watch to install as dev dependency.

error TypeError: watch is not a function ↓

cause Default import instead of named import.

fix

Use import { watch } from 'vite-plugin-watch'.

Warnings

gotcha The `command` can be a string or an array of strings. If an array, each command runs sequentially. ↓

fix For sequential commands, use array: `command: ['echo first', 'echo second']`.

deprecated No deprecated features known.

breaking No known breaking changes between versions.

Install

npm install vite-plugin-watch

yarn add vite-plugin-watch

pnpm add vite-plugin-watch

Imports

watch

wrong

import watch from 'vite-plugin-watch'

correct

import { watch } from 'vite-plugin-watch'

Named export, not default.

WatchPluginOptions

wrong

import { WatchPluginOptions } from 'vite-plugin-watch'

correct

import type { WatchPluginOptions } from 'vite-plugin-watch'

TypeScript type import.

watch (CommonJS)

wrong

const watch = require('vite-plugin-watch')

correct

const { watch } = require('vite-plugin-watch')

Use destructuring, not default assignment.

Quickstart

Configures vite-plugin-watch to run `npm run build:css` whenever any .scss file in src/ changes. Uses 1s debounce, shows output, runs on start.

// vite.config.js
import { defineConfig } from 'vite';
import { watch } from 'vite-plugin-watch';

export default defineConfig({
  plugins: [
    watch({
      pattern: 'src/**/*.scss',
      command: 'npm run build:css',
      timeout: 1000,
      silent: false,
      onInit: true
    })
  ]
});