istanbul-instrumenter-loader

3.0.1 verified Sat Apr 25 auth: no javascript maintenance

Webpack loader that instruments JavaScript files with istanbul-lib-instrument for code coverage reporting. Latest stable version is 3.0.1 (March 2018). Designed for webpack 2–4, primarily used with Karma and karma-coverage-istanbul-reporter. Supports Babel integration but must run as a post-loader. The loader has been superseded by babel-plugin-istanbul and is no longer actively maintained, but still functional for webpack 3 projects. It validates options via schema-utils but has limited flexibility compared to newer approaches.

Common errors

error Error: istanbul-instrumenter-loader requires webpack >= 2.0.0 ↓

cause Using webpack 1.x with loader (v3+) that requires webpack 2+

fix

Upgrade webpack to v2.0.0 or higher, or use the older version 2.0.0 of this loader.

error Module build failed: TypeError: Cannot read property 'instrument' of undefined ↓

cause Missing or incorrect istanbul-lib-instrument dependency; this loader depends on it internally.

fix

Run npm install istanbul-lib-instrument --save-dev or ensure it is installed as a peer dep.

error Invalid options object. Istanbul Instrumenter Loader has been initialized using an options object that does not match the API schema. ↓

cause Options validation fails due to unsupported property or wrong type

fix

Check loaded docs for valid options (esModules, compact, etc.) and ensure types (Boolean, String, Function) are correct.

Warnings

deprecated This loader is no longer actively maintained. Use babel-plugin-istanbul or c8 for new projects. ↓

fix Switch to babel-plugin-istanbul with @babel/preset-env and @babel/preset-react for Babel projects, or use c8 for native ESM support.

breaking v3.0.0 drops Node.js < 4.3 and < 5.10 support. Engines field now enforces >= 4.3 < 5.0.0 || >= 5.10. ↓

fix Upgrade Node.js to v6+ (LTS) or use v2.0.0 if stuck on older Node.

breaking v3.0.0 introduces schema validation via schema-utils. Invalid options now throw an error instead of being silently ignored. ↓

fix Ensure options object matches the schema. Check istanbul-lib-instrument API docs for valid option types.

gotcha Must set enforce: 'post' when using with Babel to avoid double instrumentation. ↓

fix Add enforce: 'post' to the rule and exclude node_modules and test files.

gotcha Sourcemaps may break if not configured correctly. Use fixWebpackSourcePaths: true in karma-coverage-istanbul-reporter. ↓

fix Set coverageIstanbulReporter.fixWebpackSourcePaths to true in karma.conf.js

Install

npm install istanbul-instrumenter-loader

yarn add istanbul-instrumenter-loader

pnpm add istanbul-instrumenter-loader

Imports

Use in webpack config

wrong

// Using require() in webpack config as a plugin
const IstanbulLoader = require('istanbul-instrumenter-loader');

correct

// webpack.config.js
{
  test: /\.js$/,
  use: { loader: 'istanbul-instrumenter-loader', options: { esModules: true } },
  enforce: 'post',
  exclude: /node_modules|\.spec\.js$/
}

This loader is used declaratively in webpack config (module.rules), not imported directly.

options

wrong

// omitting required fields or using invalid options
{
  esModules: 'yes',
  compact: 1,
  coverageVariable: undefined
}

correct

// valid options object
{
  esModules: true,
  compact: true,
  produceSourceMap: false
}

Options are validated by schema-utils; invalid types will throw errors.

test

wrong

// using wildcard require without context
require('../src/**/*.js')

correct

// pattern for test index file
const tests = require.context('./src/components/', true, /\.js$/);
tests.keys().forEach(tests);
const components = require.context('../src/components/', true, /\.js$/);
components.keys().forEach(components);

Karma webpack setup requires require.context for dynamic loading; wildcard require is not supported by webpack.

Quickstart

Sets up Karma with webpack preprocessor, instruments source files with Istanbul, and collects coverage reports.

// Install
npm install --save-dev istanbul-instrumenter-loader

// karma.conf.js
module.exports = function(config) {
  config.set({
    frameworks: ['mocha', 'chai'],
    files: ['test/index.js'],
    preprocessors: { 'test/index.js': ['webpack'] },
    webpack: {
      module: {
        rules: [{
          test: /\.js$/,
          use: { loader: 'istanbul-instrumenter-loader', options: { esModules: true } },
          enforce: 'post',
          exclude: /node_modules|\.spec\.js$/
        }]
      }
    },
    reporters: ['progress', 'coverage-istanbul'],
    coverageIstanbulReporter: {
      reports: ['text-summary'],
      fixWebpackSourcePaths: true
    },
    browsers: ['ChromeHeadless']
  });
};

// test/index.js
const tests = require.context('./src/components/', true, /\.spec\.js$/);
tests.keys().forEach(tests);
const components = require.context('../src/', true, /\.js$/);
components.keys().forEach(components);