babel-plugin-istanbul

8.0.0 verified Sat Apr 25 auth: no javascript

Babel plugin that instruments JavaScript code with Istanbul coverage. Version 8.0.0 (stable) requires Node >=18 and Babel 7/8. It automatically detects test files via nyc's exclude/include patterns and respects inline source maps. Unlike manual instrumentation, this plugin integrates seamlessly with existing Babel pipelines and tools like karma-coverage and nyc. Released as part of the istanbuljs project with regular updates and LTS support. Key differentiator: zero-config setup with nyc and Karma, and no need for separate coverage preprocessor.

Common errors

error Error: container is falsy ↓

cause Block scoping transform conflicts with instrumentation

fix

Update to babel-plugin-istanbul 7.0.0 or later, or ensure Babel config does not apply block scoping transform before instrumentation.

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

cause Plugin not installed or not in devDependencies

fix

Run: npm install --save-dev babel-plugin-istanbul

error Error: Cannot find module 'test-exclude' ↓

cause Missing dependency when using babel-plugin-istanbul v8 with npm <7 that doesn't auto-install peer dependencies

fix

Run: npm install --save-dev test-exclude

Warnings

breaking Node 8 and 10 dropped ↓

fix Upgrade Node to 12 or later

breaking test-exclude update in v8.0.0 may change file exclusion behavior ↓

fix Review exclude/include patterns; test-exclude now uses glob matching based on minimatch

deprecated Plugin options passed directly to babel-plugin-istanbul are now preferred over package.json 'nyc' config ↓

fix Move exclude/include options to Babel plugin array: ["istanbul", { exclude: ["**/*.spec.js"] }]

gotcha When using with ts-loader or other transpilers, ensure inline source maps are handled correctly. Setting useInlineSourceMaps to false can avoid memory issues. ↓

fix Set useInlineSourceMaps: false in plugin options if multiple build steps cause memory bloat.

gotcha Must set nyc.sourceMap and nyc.instrument to false in package.json to avoid double instrumentation ↓

fix Add 'nyc': { 'sourceMap': false, 'instrument': false }

Install

npm install babel-plugin-istanbul

yarn add babel-plugin-istanbul

pnpm add babel-plugin-istanbul

Imports

default
wrong
```
const babelPluginIstanbul = require('babel-plugin-istanbul')
```
correct
```
import babelPluginIstanbul from 'babel-plugin-istanbul'
```
Default import works in ESM environments. For older Node versions, use require but ensure Babel is configured to handle it.

babelPluginIstanbul

wrong

const { default: babelPluginIstanbul } = require('babel-plugin-istanbul');

correct

const babelPluginIstanbul = require('babel-plugin-istanbul');

CommonJS usage: direct require works; no need to destructure default.

plugin configuration
wrong
```
plugins: ['babel-plugin-istanbul']
```
correct
```
plugins: ['istanbul'] or plugins: [['istanbul', { exclude: ['**/*.spec.js'] }]]
```
In .babelrc or babel.config.js, use the shorthand name 'istanbul' not the full package name.

Quickstart

Shows minimal setup to instrument code with babel-plugin-istanbul: install, configure .babelrc for test env, configure nyc to skip own instrumentation, and run tests with nyc.

// Install: npm install --save-dev babel-plugin-istanbul
// In .babelrc:
{
  "env": {
    "test": {
      "plugins": ["istanbul"]
    }
  }
}
// In package.json, configure nyc to not re-instrument:
"nyc": {
  "sourceMap": false,
  "instrument": false
}
// Run tests: npx nyc --reporter=lcov --reporter=text npx mocha test/*.js