0
# Rollup Plugin Istanbul
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: rollup-plugin-istanbul
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install --save-dev rollup-plugin-istanbul`
10

11
## Core Imports
12

13
```javascript
14
import istanbul from 'rollup-plugin-istanbul';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const istanbul = require('rollup-plugin-istanbul');
21
```
22

23
## Basic Usage
24

25
```javascript
26
import { rollup } from 'rollup';
27
import istanbul from 'rollup-plugin-istanbul';
28

29
// Basic configuration
30
rollup({
31
  entry: 'main.js',
32
  plugins: [
33
    istanbul({
34
      exclude: ['test/**/*.js']
35
    })
36
  ]
37
}).then(...)
38

39
// With custom instrumenter configuration
40
rollup({
41
  entry: 'main.js',
42
  plugins: [
43
    istanbul({
44
      include: ['src/**/*.js'],
45
      exclude: ['test/**/*.js', 'spec/**/*.js'],
46
      instrumenterConfig: {
47
        esModules: true,
48
        compact: false,
49
        produceSourceMap: true
50
      }
51
    })
52
  ]
53
})
54
```
55

56
## Capabilities
57

58
### Plugin Factory Function
59

60
Creates a Rollup plugin instance for Istanbul code coverage instrumentation.
61

62
```javascript { .api }
63
/**
64
 * Creates a Rollup plugin instance for Istanbul code coverage instrumentation.
65
 * 
66
 * @param {Object} [options={}] - Configuration options for the plugin
67
 * @param {string|string[]} [options.include] - Minimatch pattern(s) for files to include
68
 * @param {string|string[]} [options.exclude] - Minimatch pattern(s) for files to exclude  
69
 * @param {Object} [options.instrumenterConfig] - Configuration passed to Istanbul instrumenter
70
 * @param {boolean} [options.instrumenterConfig.esModules=true] - Enable ES module instrumentation
71
 * @param {boolean} [options.instrumenterConfig.compact=true] - Generate compact instrumented code
72
 * @param {boolean} [options.instrumenterConfig.produceSourceMap=true] - Generate source maps
73
 * @param {boolean} [options.instrumenterConfig.autoWrap=true] - Automatically wrap code
74
 * @param {boolean} [options.instrumenterConfig.preserveComments=true] - Preserve comments
75
 * @param {Object} [options.instrumenter] - Alternative instrumenter implementation
76
 * @returns {Object} Rollup plugin object with name and transform properties
77
 */
78
function istanbul(options);
79

80
// Plugin object returned by istanbul function
81
// {
82
//   name: string,           // Plugin name ("istanbul")
83
//   transform: function     // Transform function for code instrumentation
84
// }
85

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

90
**Usage Examples:**
91

92
```javascript
93
// Exclude test files from coverage
94
istanbul({
95
  exclude: ['test/**/*.js', 'spec/**/*.js']
96
})
97

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

104
// Custom instrumenter configuration
105
istanbul({
106
  exclude: ['test/**/*.js'],
107
  instrumenterConfig: {
108
    esModules: true,
109
    compact: true,
110
    produceSourceMap: true,
111
    autoWrap: true,
112
    preserveComments: true
113
  }
114
})
115

116
// Using with custom instrumenter (e.g., isparta)
117
istanbul({
118
  exclude: ['test/**/*.js'],
119
  instrumenter: require('isparta')
120
})
121
```
122

123
### Configuration Options
124

125
#### include
126

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

129
- **Type**: `string | string[]`
130
- **Default**: All files included
131
- **Examples**: `'src/**/*.js'`, `['src/**/*.js', 'lib/**/*.js']`
132

133
#### exclude
134

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

137
- **Type**: `string | string[]`
138
- **Default**: No exclusions
139
- **Examples**: `'test/**/*.js'`, `['test/**/*.js', 'spec/**/*.js']`
140

141
#### instrumenterConfig
142

143
Configuration options passed to the Istanbul instrumenter.
144

145
- **Type**: `Object`
146
- **Default**: 
147
  ```javascript
148
  {
149
    esModules: true,
150
    compact: true,
151
    produceSourceMap: true,
152
    autoWrap: true,
153
    preserveComments: true
154
  }
155
  ```
156

157
Available instrumenter configuration options:
158
- `esModules`: Enable ES module instrumentation
159
- `compact`: Generate compact instrumented code
160
- `produceSourceMap`: Generate source maps for instrumented code
161
- `autoWrap`: Automatically wrap code in anonymous function
162
- `preserveComments`: Preserve comments in instrumented code
163

164
#### instrumenter
165

166
Alternative instrumenter implementation that implements the Istanbul API.
167

168
- **Type**: `Object`
169
- **Default**: `istanbul-lib-instrument`
170
- **Example**: `require('isparta')` for ES6+ transpilation
171

172
## Integration Examples
173

174
### With Karma Testing
175

176
```javascript
177
// karma.conf.js
178
const istanbul = require('rollup-plugin-istanbul');
179

180
module.exports = function (config) {
181
  config.set({
182
    files: ['test/*.js'],
183
    preprocessors: {
184
      'test/*.js': ['rollup']
185
    },
186
    rollupPreprocessor: {
187
      rollup: {
188
        plugins: [
189
          istanbul({
190
            exclude: ['test/*.js']
191
          })
192
        ]
193
      }
194
    },
195
    reporters: ['coverage']
196
  });
197
};
198
```
199

200
### With Babel and ES2015
201

202
```javascript
203
// karma.conf.js
204
const istanbul = require('rollup-plugin-istanbul');
205
const babel = require('@rollup/plugin-babel').babel;
206

207
module.exports = function (config) {
208
  config.set({
209
    files: ['test/*.js'],
210
    preprocessors: {
211
      'test/*.js': ['rollup']
212
    },
213
    rollupPreprocessor: {
214
      plugins: [
215
        istanbul({
216
          exclude: ['test/*.js']
217
        }),
218
        babel({ babelHelpers: 'bundled' })
219
      ],
220
      output: {
221
        format: 'iife',
222
        sourceMap: 'inline'
223
      }
224
    },
225
    reporters: ['coverage'],
226
    coverageReporter: {
227
      dir: 'coverage',
228
      includeAllSources: true,
229
      reporters: [
230
        { type: 'text' },
231
        { type: 'html', subdir: 'html' },
232
        { type: 'lcov', subdir: './' }
233
      ]
234
    }
235
  });
236
};
237
```
238

239
## Plugin Behavior
240

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

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

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

250
## Platform Support
251

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