esbuild-plugin-istanbul

0.3.0 verified Fri May 01 auth: no javascript

An esbuild plugin that instruments JavaScript/TypeScript source code with Istanbul/nyc code coverage instrumentation during the build process. Version 0.3.0 is the current stable release; the package is updated infrequently with no fixed cadence. It works as an esbuild plugin, applying Istanbul's instrumentation to files matched by configurable filters and loaders (js, jsx, ts, tsx). Unlike alternatives that require Babel or Webpack, this plugin integrates directly with esbuild's fast build pipeline. It ships TypeScript definitions and supports both ESM and CJS environments. Key differentiator: native esbuild integration without additional transform steps.

Common errors

error Error: Cannot find module 'esbuild-plugin-istanbul' ↓

cause Package not installed or import path is incorrect.

fix

Run npm install esbuild-plugin-istanbul and ensure import uses correct named export.

error Module 'esbuild-plugin-istanbul' has no default export ↓

cause Attempting default import instead of named import.

fix

Use import { esbuildPluginIstanbul } from 'esbuild-plugin-istanbul'.

error TypeError: esbuildPluginIstanbul is not a function ↓

cause CommonJS require without destructuring returns an object with the function as a property.

fix

Use const { esbuildPluginIstanbul } = require('esbuild-plugin-istanbul').

Warnings

gotcha Must specify correct loader for file type (js/jsx/ts/tsx). Using wrong loader may break instrumentation. ↓

fix Set loader to match file extension: 'js' for .js, 'jsx' for .jsx, 'ts' for .ts, 'tsx' for .tsx.

gotcha The plugin only processes files matched by the filter regex. If filter is too narrow, some files may be skipped. ↓

fix Ensure filter regex matches all files you intend to instrument (e.g., /\.(js|jsx|ts|tsx)$/).

gotcha Instrumentation may significantly slow down builds for large projects. ↓

fix Consider using incremental builds or caching mechanisms in development.

deprecated Plugin options may change in future minor versions; no deprecation notices yet. ↓

fix Pin exact version in package.json.

Install

npm install esbuild-plugin-istanbul

yarn add esbuild-plugin-istanbul

pnpm add esbuild-plugin-istanbul

Imports

esbuildPluginIstanbul

wrong

import esbuildPluginIstanbul from 'esbuild-plugin-istanbul'

correct

import { esbuildPluginIstanbul } from 'esbuild-plugin-istanbul'

This is a named export, not a default export. Both ESM and CJS work.

esbuildPluginIstanbul

wrong

const esbuildPluginIstanbul = require('esbuild-plugin-istanbul')

correct

const { esbuildPluginIstanbul } = require('esbuild-plugin-istanbul')

CommonJS destructuring is required because it's a named export.

PluginOptions

import type { PluginOptions } from 'esbuild-plugin-istanbul'

TypeScript only; not available at runtime.

Quickstart

Shows how to instrument TypeScript source with Istanbul coverage using esbuild.

import { esbuildPluginIstanbul } from 'esbuild-plugin-istanbul';
import * as esbuild from 'esbuild';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outdir: 'dist',
  plugins: [
    esbuildPluginIstanbul({
      filter: /\.tsx?$/,
      loader: 'ts',
      name: 'istanbul',
    }),
  ],
});