vite-plugin-run

0.9.0 verified Mon Apr 27 auth: no javascript

Vite plugin that runs shell commands on file changes or server startup. v0.9.0 (released 2025) drops CommonJS support and migrates to bun/tsdown. Key plugin options: silent, skipDts, input. Runner options include pattern (minimatch), condition (function), debounce, startup, build, onFileChanged. Uses execa for shell commands. Maintained by Enzo Innocenzi, updates ~yearly.

Common errors

error const { run } = require('vite-plugin-run') ↓

cause CJS require() used with ESM-only module (v0.9.0+).

fix

Use import: import { run } from 'vite-plugin-run'

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

cause Package not installed or vite version incompatible (requires vite ^8.0.8).

fix

Run 'npm install vite-plugin-run' and ensure vite 8.x is installed.

error TypeError: run is not a function ↓

cause Default import used incorrectly (e.g., import vitePluginRun from 'vite-plugin-run').

fix

Use named import: import { run } from 'vite-plugin-run'

error ERR_REQUIRE_ESM: require() of ES Module ↓

cause Trying to require an ESM-only package in a CommonJS context.

fix

Switch project to ESM ("type": "module" in package.json) or use dynamic import: const { run } = await import('vite-plugin-run')

Warnings

breaking v0.9.0 removed CJS support; package is ESM-only. ↓

fix Use ES module imports with 'import { run } from ...' instead of 'require()'.

breaking v0.8.0 dropped 'throttle' option; only 'debounce' is supported. ↓

fix Remove any usage of 'throttle' from runner options and use 'debounce' (milliseconds).

breaking v0.8.0 upgraded dependencies, may require Vite 4.4+. ↓

fix Ensure vite version meets peer dependency requirements (vite ^8.0.8 for v0.9.0).

deprecated 'onFileChanged' callback is deprecated; plan to remove in v1.0. ↓

fix Use 'condition' or 'pattern' to react to file changes instead.

gotcha If 'pattern' is specified without 'condition', the command runs for any file matching pattern. Ensure patterns are specific enough to avoid unnecessary command execution. ↓

fix Use narrow minimatch patterns or add a 'condition' function for fine-grained control.

Install

npm install vite-plugin-run

yarn add vite-plugin-run

pnpm add vite-plugin-run

Imports

run

wrong

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

correct

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

v0.9.0 is ESM-only; use import syntax. CommonJS require will fail.

RunOptions
wrong
```
import { RunOptions } from 'vite-plugin-run'
```
correct
```
import type { RunOptions } from 'vite-plugin-run'
```
TypeScript users should use 'import type' for type-only imports. Available since v0.4.0.

Plugin

wrong

import vitePluginRun from 'vite-plugin-run'

correct

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

The plugin has no default export; always use named import 'run'.

Quickstart

Basic Vite plugin setup to run eslint on TypeScript file changes with 100ms debounce.

import { defineConfig } from 'vite';
import { run } from 'vite-plugin-run';

export default defineConfig({
  plugins: [
    run([
      {
        name: 'lint',
        run: ['eslint', '--fix'],
        pattern: 'src/**/*.ts',
        debounce: 100,
      },
    ]),
  ],
});