Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
im
✓ const im = require('istanbul-middleware');
✗ import im from 'istanbul-middleware';
This package is a CommonJS module from an older era of Node.js. ESM `import` syntax is not supported and will fail.
hookLoader
✓ im.hookLoader(__dirname);
Used to instrument server-side JavaScript files by hooking Node.js's `require()` mechanism. Must be called before other application code is `require()`-d.
createHandler
✓ app.use('/coverage', im.createHandler());
Creates a Connect/Express middleware to expose coverage endpoints like `/coverage/`, `/coverage/reset`, `/coverage/download`, and `/coverage/client`.
createClientHandler
✓ app.use(im.createClientHandler(__dirname));
Creates a middleware to serve instrumented JavaScript files to the browser, enabling client-side code coverage collection.
This quickstart demonstrates how to integrate `istanbul-middleware` into an Express application for both server-side and client-side code coverage. It shows how to conditionally enable coverage, hook the Node.js `require()` loader, and set up the `/coverage` endpoints for reports, resets, downloads, and client-side data submission, as well as serving instrumented JavaScript files.
const im = require('istanbul-middleware'),
express = require('express'),
app = express();
// Determine if coverage is enabled, e.g., via environment variable
const isCoverageEnabled = (process.env.COVERAGE === "true");
// Hook the Node.js loader for server-side coverage instrumentation.
// This MUST happen before your application's code is 'require()'-d.
if (isCoverageEnabled) {
console.log('Hook loader for coverage - ensure this is not production!');
im.hookLoader(__dirname); // Instruments all files under __dirname except node_modules
}
// Require your main application code AFTER the loader is hooked
const appRoutes = require('./lib/routes'); // Example application code
// Set up basic Express middleware (e.g., body parsers, static files)
app.use(express.json());
app.use(express.static('public'));
// Add the coverage handler if enabled
if (isCoverageEnabled) {
// Enable coverage endpoints under /coverage
// This will expose /coverage, /coverage/reset, /coverage/download, /coverage/client
app.use('/coverage', im.createHandler());
}
// Add your application's router and other endpoints
app.use('/', appRoutes);
// For client-side coverage, serve instrumented JS files.
// Place this middleware before your static file handler for JavaScript assets.
if (isCoverageEnabled) {
// All JS files under the root will be sent instrumented to the browser
app.use(im.createClientHandler(__dirname));
}
app.listen(3000, () => {
console.log('App listening on port 3000');
if (isCoverageEnabled) {
console.log('Coverage enabled via /coverage endpoints.');
}
});
Debug
Known issues
breakingThe package is explicitly labeled as 'experimental' and known to work only for 'narrow use-cases' such as Express 3. It has not been updated in approximately 10 years and is considered abandoned. Compatibility with newer Node.js versions (e.g., Node.js 14+), Express 4+, or other modern web frameworks is highly unlikely, and significant breakage is expected.fixDo not use this package in new projects. For existing projects, consider migrating to modern alternatives within the `istanbuljs` ecosystem (e.g., `@istanbuljs/nyc-config-base`, `nyc`) which are actively maintained and support current JavaScript features and Node.js environments.
affects: >=0.2.3 (hypothetical), or generally with modern Node/Express versions
gotchaUsing `im.hookLoader()` globally modifies Node.js's `require()` function to instrument code on the fly. The README explicitly warns: 'ensure this is not production!'. This can have performance implications and introduce unexpected behavior in a production environment.fixOnly enable `istanbul-middleware` in development or test environments. Guard its usage with environment checks (e.g., `process.env.COVERAGE == "true"`) to prevent accidental deployment to production.
affects: >=0.2.0
gotchaThe `hookLoader` call must occur very early in your application's lifecycle, *before* any other application code that needs to be covered is `require()`-d. If not, those modules will load uninstrumented, and their coverage will not be tracked.fixPlace `im.hookLoader()` at the absolute entry point of your server application, typically the first lines of your main server file, conditioned on your `isCoverageEnabled` flag.
affects: >=0.2.0
deprecatedThis package exclusively uses CommonJS `require()` syntax and does not support ES Modules (`import`/`export`). Attempts to `import` it will result in errors in an ESM context.fixEnsure your project is configured for CommonJS if you absolutely must use this package. For new projects, migrate to modern coverage tools that natively support ESM.
affects: >=0.2.0 (ESM-related issues on modern Node.js versions)
Errors
Common errors & fixes
TypeError: app.use is not a function
The `app` object is not a valid Express or Connect application instance, or you are trying to use an older `express3` instance with a newer API or vice-versa.
fixEnsure `app` is a correctly initialized Express application (e.g., `const app = express();`) and that your Express version is compatible with this middleware (targeting Express 3).
Error: Cannot find module 'istanbul-middleware'
The package `istanbul-middleware` is not installed or not resolvable in the current Node.js environment.
fixRun `npm install istanbul-middleware` to add the package to your project dependencies.
SyntaxError: Cannot use import statement outside a module
You are attempting to use ES Module `import` syntax (`import im from 'istanbul-middleware'`) in a CommonJS environment, or vice-versa, for a package that only supports CommonJS.
fixReplace `import im from 'istanbul-middleware';` with `const im = require('istanbul-middleware');`. Audit
Dependencies
istanbulrequiredCore coverage engine for instrumentation and reporting. While not a direct `dependencies` entry in `package.json`, it's the fundamental tool this middleware integrates with.
expressoptionalCommonly used with this middleware, as shown in examples and mentioned in the description ('express3 app').
connectoptionalThe middleware base this package was built for, as indicated by its name and nature.