{"id":17719,"library":"istanbul-middleware","title":"Istanbul Middleware for Connect/Express","description":"istanbul-middleware is a Connect/Express middleware package designed to integrate Istanbul code coverage into Node.js applications, supporting both server-side and browser-side code coverage during functional tests. It allows developers to hook `require()` for server-side instrumentation, expose dynamic HTML coverage reports, reset coverage data, and download reports via special HTTP endpoints (e.g., `/coverage`). It also provides mechanisms to instrument JavaScript files delivered to the browser and aggregate client-side coverage data posted back to the server. The package's current stable version is 0.2.2, with the last update approximately 10 years ago (as of 2024). It was explicitly labeled as 'experimental' and suitable for 'narrow use-cases' like Express 3. Its key differentiator was providing a server-integrated solution for coverage, aggregating data from various sources. Due to its age and lack of updates, the project is considered abandoned, and newer alternatives for code coverage (like the `istanbuljs` ecosystem) should be preferred.","status":"abandoned","version":"0.2.2","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/gotwarlost/istanbul-middleware","tags":["javascript"],"install":[{"cmd":"npm install istanbul-middleware","lang":"bash","label":"npm"},{"cmd":"yarn add istanbul-middleware","lang":"bash","label":"yarn"},{"cmd":"pnpm add istanbul-middleware","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core coverage engine for instrumentation and reporting. While not a direct `dependencies` entry in `package.json`, it's the fundamental tool this middleware integrates with.","package":"istanbul","optional":false},{"reason":"Commonly used with this middleware, as shown in examples and mentioned in the description ('express3 app').","package":"express","optional":true},{"reason":"The middleware base this package was built for, as indicated by its name and nature.","package":"connect","optional":true}],"imports":[{"note":"This package is a CommonJS module from an older era of Node.js. ESM `import` syntax is not supported and will fail.","wrong":"import im from 'istanbul-middleware';","symbol":"im","correct":"const im = require('istanbul-middleware');"},{"note":"Used to instrument server-side JavaScript files by hooking Node.js's `require()` mechanism. Must be called before other application code is `require()`-d.","symbol":"hookLoader","correct":"im.hookLoader(__dirname);"},{"note":"Creates a Connect/Express middleware to expose coverage endpoints like `/coverage/`, `/coverage/reset`, `/coverage/download`, and `/coverage/client`.","symbol":"createHandler","correct":"app.use('/coverage', im.createHandler());"},{"note":"Creates a middleware to serve instrumented JavaScript files to the browser, enabling client-side code coverage collection.","symbol":"createClientHandler","correct":"app.use(im.createClientHandler(__dirname));"}],"quickstart":{"code":"const im = require('istanbul-middleware'),\n    express = require('express'),\n    app = express();\n\n// Determine if coverage is enabled, e.g., via environment variable\nconst isCoverageEnabled = (process.env.COVERAGE === \"true\");\n\n// Hook the Node.js loader for server-side coverage instrumentation.\n// This MUST happen before your application's code is 'require()'-d.\nif (isCoverageEnabled) {\n    console.log('Hook loader for coverage - ensure this is not production!');\n    im.hookLoader(__dirname); // Instruments all files under __dirname except node_modules\n}\n\n// Require your main application code AFTER the loader is hooked\nconst appRoutes = require('./lib/routes'); // Example application code\n\n// Set up basic Express middleware (e.g., body parsers, static files)\napp.use(express.json());\napp.use(express.static('public'));\n\n// Add the coverage handler if enabled\nif (isCoverageEnabled) {\n    // Enable coverage endpoints under /coverage\n    // This will expose /coverage, /coverage/reset, /coverage/download, /coverage/client\n    app.use('/coverage', im.createHandler());\n}\n\n// Add your application's router and other endpoints\napp.use('/', appRoutes);\n\n// For client-side coverage, serve instrumented JS files.\n// Place this middleware before your static file handler for JavaScript assets.\nif (isCoverageEnabled) {\n    // All JS files under the root will be sent instrumented to the browser\n    app.use(im.createClientHandler(__dirname));\n}\n\napp.listen(3000, () => {\n    console.log('App listening on port 3000');\n    if (isCoverageEnabled) {\n        console.log('Coverage enabled via /coverage endpoints.');\n    }\n});\n","lang":"javascript","description":"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."},"warnings":[{"fix":"Do 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.","message":"The 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.","severity":"breaking","affected_versions":">=0.2.3 (hypothetical), or generally with modern Node/Express versions"},{"fix":"Only 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.","message":"Using `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.","severity":"gotcha","affected_versions":">=0.2.0"},{"fix":"Place `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.","message":"The `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.","severity":"gotcha","affected_versions":">=0.2.0"},{"fix":"Ensure 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.","message":"This 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.","severity":"deprecated","affected_versions":">=0.2.0 (ESM-related issues on modern Node.js versions)"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure `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).","cause":"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.","error":"TypeError: app.use is not a function"},{"fix":"Run `npm install istanbul-middleware` to add the package to your project dependencies.","cause":"The package `istanbul-middleware` is not installed or not resolvable in the current Node.js environment.","error":"Error: Cannot find module 'istanbul-middleware'"},{"fix":"Replace `import im from 'istanbul-middleware';` with `const im = require('istanbul-middleware');`.","cause":"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.","error":"SyntaxError: Cannot use import statement outside a module"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}