Istanbul Middleware for TypeScript

1.1.4 verified Thu Apr 23 auth: no javascript

istanbul-middleware-ts is a TypeScript-first middleware designed for integrating Istanbul code coverage reporting into Node.js applications, primarily with Express.js. It provides HTTP endpoints to collect, reset, merge, report, and download code coverage data. The package is currently at version 1.1.4, indicating active maintenance with several recent minor releases, and offers complete TypeScript support with type definitions. Its release cadence appears to be driven by feature additions and bug fixes within the 1.x series. A key differentiator is its modern TypeScript implementation that is compatible with the API of the original `istanbul-middleware`, making it a drop-in replacement for users seeking enhanced type safety and up-to-date Node.js practices. It offers robust functionality for CI/CD pipelines and local development environments by enabling dynamic coverage data management, HTML report generation, and LCOV/ZIP package downloads, alongside features like differential coverage reporting against git targets.

Common errors

error Cannot find module 'express' or its corresponding type declarations. ↓

cause Express.js is a peer dependency and must be installed separately by your project.

fix

Install Express.js and its type definitions: npm install express @types/express

error TypeError: app.use is not a function ↓

cause Attempting to use the `istanbul-middleware-ts` handler without a valid Express application instance.

fix

Ensure app is an instance of express() before calling app.use().

error ReferenceError: require is not defined in ES module scope ↓

cause Using CommonJS `require` syntax in a TypeScript or ES Module project (e.g., `package.json` `"type": "module"` or `.mjs` files).

fix

Use ES module import syntax: import { createHandler } from 'istanbul-middleware-ts';

Warnings

gotcha The `/reset` endpoint accessible via GET requests is disabled by default for security reasons and to prevent accidental data loss. It must be explicitly enabled. ↓

fix Pass `{ resetOnGet: true }` to the `createHandler` options to enable `GET /reset` functionality.

gotcha Differential coverage functionality (GET /diff, GET /diff/info) requires the Python `diff-cover` package to be installed globally or available in the system's PATH, and the `diffTarget` option to be configured. ↓

fix Install `diff-cover` (e.g., `pip install diff-cover`) and configure the `diffTarget` option in the `createHandler` options to a branch, commit, or tag.

Install

npm install istanbul-middleware-ts

yarn add istanbul-middleware-ts

pnpm add istanbul-middleware-ts

Imports

createHandler

wrong

const { createHandler } = require('istanbul-middleware-ts');

correct

import { createHandler } from 'istanbul-middleware-ts';

Primary export for middleware creation, typically used with Express.js `app.use()`.

getCoverageObject

wrong

const { getCoverageObject } = require('istanbul-middleware-ts');

correct

import { getCoverageObject } from 'istanbul-middleware-ts';

Use for programmatic access to the current collected Istanbul coverage data object.

resetCoverage

wrong

const { resetCoverage } = require('istanbul-middleware-ts');

correct

import { resetCoverage } from 'istanbul-middleware-ts';

Use for programmatic resetting of the coverage data collected by the middleware.

Quickstart

This example sets up an Express.js server with the Istanbul middleware, making coverage reports and data available at the `/coverage` endpoint, and enabling GET requests to reset coverage.

import express from "express";
import { createHandler } from "istanbul-middleware-ts";

const app = express();

// Add Istanbul middleware
app.use(
  "/coverage",
  createHandler({
    resetOnGet: true // Allow GET requests to reset coverage
  })
);

app.listen(3000, () => {
  console.log("Server running on http://localhost:3000");
  console.log("Coverage available at http://localhost:3000/coverage");
});