or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-rollup-plugin-istanbul

Seamless integration between Rollup and Istanbul code coverage instrumentation.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/rollup-plugin-istanbul@5.0.x

To install, run

npx @tessl/cli install tessl/npm-rollup-plugin-istanbul@5.0.0

index.mddocs/

Rollup Plugin Istanbul

A Rollup plugin that seamlessly integrates Istanbul code coverage instrumentation into the Rollup bundling process. The plugin instruments JavaScript source code for coverage analysis while excluding test files from instrumentation, making it ideal for projects that need to bundle both application code and tests separately.

Package Information

  • Package Name: rollup-plugin-istanbul
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install --save-dev rollup-plugin-istanbul

Core Imports

import istanbul from 'rollup-plugin-istanbul';

For CommonJS:

const istanbul = require('rollup-plugin-istanbul');

Basic Usage

import { rollup } from 'rollup';
import istanbul from 'rollup-plugin-istanbul';

// Basic configuration
rollup({
  entry: 'main.js',
  plugins: [
    istanbul({
      exclude: ['test/**/*.js']
    })
  ]
}).then(...)

// With custom instrumenter configuration
rollup({
  entry: 'main.js',
  plugins: [
    istanbul({
      include: ['src/**/*.js'],
      exclude: ['test/**/*.js', 'spec/**/*.js'],
      instrumenterConfig: {
        esModules: true,
        compact: false,
        produceSourceMap: true
      }
    })
  ]
})

Capabilities

Plugin Factory Function

Creates a Rollup plugin instance for Istanbul code coverage instrumentation.

/**
 * Creates a Rollup plugin instance for Istanbul code coverage instrumentation.
 * 
 * @param {Object} [options={}] - Configuration options for the plugin
 * @param {string|string[]} [options.include] - Minimatch pattern(s) for files to include
 * @param {string|string[]} [options.exclude] - Minimatch pattern(s) for files to exclude  
 * @param {Object} [options.instrumenterConfig] - Configuration passed to Istanbul instrumenter
 * @param {boolean} [options.instrumenterConfig.esModules=true] - Enable ES module instrumentation
 * @param {boolean} [options.instrumenterConfig.compact=true] - Generate compact instrumented code
 * @param {boolean} [options.instrumenterConfig.produceSourceMap=true] - Generate source maps
 * @param {boolean} [options.instrumenterConfig.autoWrap=true] - Automatically wrap code
 * @param {boolean} [options.instrumenterConfig.preserveComments=true] - Preserve comments
 * @param {Object} [options.instrumenter] - Alternative instrumenter implementation
 * @returns {Object} Rollup plugin object with name and transform properties
 */
function istanbul(options);

// Plugin object returned by istanbul function
// {
//   name: string,           // Plugin name ("istanbul")
//   transform: function     // Transform function for code instrumentation
// }

// Transform function signature:
// transform(code: string, id: string) -> { code: string, map: object } | undefined

Usage Examples:

// Exclude test files from coverage
istanbul({
  exclude: ['test/**/*.js', 'spec/**/*.js']
})

// Include only specific source files
istanbul({
  include: ['src/**/*.js', 'lib/**/*.js'],
  exclude: ['src/**/*.test.js']
})

// Custom instrumenter configuration
istanbul({
  exclude: ['test/**/*.js'],
  instrumenterConfig: {
    esModules: true,
    compact: true,
    produceSourceMap: true,
    autoWrap: true,
    preserveComments: true
  }
})

// Using with custom instrumenter (e.g., isparta)
istanbul({
  exclude: ['test/**/*.js'],
  instrumenter: require('isparta')
})

Configuration Options

include

Minimatch pattern(s) for files to include in instrumentation. If omitted, all files are included by default.

  • Type: string | string[]
  • Default: All files included
  • Examples: 'src/**/*.js', ['src/**/*.js', 'lib/**/*.js']

exclude

Minimatch pattern(s) for files to exclude from instrumentation. Commonly used to exclude test files.

  • Type: string | string[]
  • Default: No exclusions
  • Examples: 'test/**/*.js', ['test/**/*.js', 'spec/**/*.js']

instrumenterConfig

Configuration options passed to the Istanbul instrumenter.

  • Type: Object
  • Default: 
    {
  esModules: true,
  compact: true,
  produceSourceMap: true,
  autoWrap: true,
  preserveComments: true
}

Available instrumenter configuration options:

  • esModules: Enable ES module instrumentation
  • compact: Generate compact instrumented code
  • produceSourceMap: Generate source maps for instrumented code
  • autoWrap: Automatically wrap code in anonymous function
  • preserveComments: Preserve comments in instrumented code

instrumenter

Alternative instrumenter implementation that implements the Istanbul API.

  • Type: Object
  • Default: istanbul-lib-instrument
  • Example: require('isparta') for ES6+ transpilation

Integration Examples

With Karma Testing

// karma.conf.js
const istanbul = require('rollup-plugin-istanbul');

module.exports = function (config) {
  config.set({
    files: ['test/*.js'],
    preprocessors: {
      'test/*.js': ['rollup']
    },
    rollupPreprocessor: {
      rollup: {
        plugins: [
          istanbul({
            exclude: ['test/*.js']
          })
        ]
      }
    },
    reporters: ['coverage']
  });
};

With Babel and ES2015

// karma.conf.js
const istanbul = require('rollup-plugin-istanbul');
const babel = require('@rollup/plugin-babel').babel;

module.exports = function (config) {
  config.set({
    files: ['test/*.js'],
    preprocessors: {
      'test/*.js': ['rollup']
    },
    rollupPreprocessor: {
      plugins: [
        istanbul({
          exclude: ['test/*.js']
        }),
        babel({ babelHelpers: 'bundled' })
      ],
      output: {
        format: 'iife',
        sourceMap: 'inline'
      }
    },
    reporters: ['coverage'],
    coverageReporter: {
      dir: 'coverage',
      includeAllSources: true,
      reporters: [
        { type: 'text' },
        { type: 'html', subdir: 'html' },
        { type: 'lcov', subdir: './' }
      ]
    }
  });
};

Plugin Behavior

The plugin integrates into Rollup's transform pipeline with the following behavior:

  1. File Filtering: Uses @rollup/pluginutils.createFilter to determine which files to instrument based on include/exclude patterns
  2. Code Instrumentation: Applies Istanbul instrumentation to filtered files during the transform phase
  3. Source Map Preservation: Maintains source map accuracy through the instrumentation process
  4. Coverage Integration: Generates instrumented code that integrates with Istanbul's coverage collection system

The plugin returns undefined for files that don't match the filter criteria, allowing them to pass through unchanged.

Platform Support

  • Node.js: Primary runtime environment
  • Rollup Versions: Compatible with v1.20.0, v2.x, v3.x, v4.x
  • Module Systems: Supports both ES modules and CommonJS via dual package exports
  • Source Maps: Full support with preservation through instrumentation process