vite-plugin-istanbul

8.0.0 verified Sat Apr 25 auth: no javascript

Vite plugin that instruments source code with Istanbul/NYC for code coverage, similar to Webpack's istanbul-instrumenter-loader. Current stable version 8.0.0 (released March 2026) supports Vite >=4. Maintained by community with regular releases. Key differentiator: seamless integration with Vite's build pipeline, automatic TypeScript/JSX/Vue support, and optional environment variable gating to avoid instrumenting production builds. Designed for development/test coverage only.

Common errors

error Cannot find module '@babel/generator' ↓

cause Missing dependency 'babel__generator' or its types.

fix

Run npm install -D @types/babel__generator (or upgrade to v7.2.1+ where it's included).

error TypeError: IstanbulPlugin is not a function ↓

cause Using named import instead of default import.

fix

Use import IstanbulPlugin from 'vite-plugin-istanbul' (no curly braces).

error Plugin loaded but no coverage data generated ↓

cause Environment variable VITE_COVERAGE is not set to 'true' when requireEnv is not explicitly set, or extensions not included.

fix

Set VITE_COVERAGE=true, or set requireEnv: false, and ensure your file extensions match the extension option.

error Error: require() of ES Module not supported ↓

cause Using CommonJS require() on the ESM package.

fix

Use dynamic import: const IstanbulPlugin = (await import('vite-plugin-istanbul')).default or configure your project for ESM.

Warnings

breaking Removed upper range constraint on Vite peer dependency; may cause conflicts with older Vite versions during install. ↓

fix Ensure your Vite version is compatible (>=4). If using Vite 5/6, test instrumentation after upgrade.

deprecated requireEnv option default behavior changed; previously not requiring env by default, now requires explicit 'true'. ↓

fix Set requireEnv: true explicitly if you want env-gated instrumentation, or set it to false to always instrument.

gotcha The plugin is intended for development/testing only; using it in production may slow down builds and include coverage code in bundles. ↓

fix Use requireEnv: true and set VITE_COVERAGE=false or unset in production CI.

breaking Default export usage changed; may break projects using CommonJS require without .default property. ↓

fix Use `const IstanbulPlugin = require('vite-plugin-istanbul').default` for CJS.

gotcha Instrumentation may not work with Vite's SSR mode or library mode; only tested with build/serve for client-side code. ↓

fix If using SSR, consider alternative coverage approaches or test with a separate config.

Install

npm install vite-plugin-istanbul

yarn add vite-plugin-istanbul

pnpm add vite-plugin-istanbul

Imports

IstanbulPlugin

wrong

import { IstanbulPlugin } from 'vite-plugin-istanbul'

correct

import IstanbulPlugin from 'vite-plugin-istanbul'

Default export only. Named import will resolve to undefined.

type IstanbulPluginOptions
```
import type { IstanbulPluginOptions } from 'vite-plugin-istanbul'
```
Type is exported as a named type. Use 'import type' for tree-shaking.
default export usage with require
wrong
```
const IstanbulPlugin = require('vite-plugin-istanbul')
```
correct
```
const IstanbulPlugin = require('vite-plugin-istanbul').default
```
CommonJS users must use '.default' because the module uses ESM default export.

Quickstart

Basic setup: enable Istanbul instrumentation only when VITE_COVERAGE environment variable is set to true, targeting .ts/.vue files in src.

// vite.config.ts
import IstanbulPlugin from 'vite-plugin-istanbul';

export default defineConfig({
  plugins: [
    IstanbulPlugin({
      include: 'src/**',
      exclude: ['node_modules', 'tests/**'],
      extension: ['.js', '.ts', '.tsx', '.vue'],
      requireEnv: true // only instruments when VITE_COVERAGE=true
    })
  ]
});

// Run: VITE_COVERAGE=true npx vite build