istanbuljs is the library layer under the coverage tools you already use

The repository says outright that you probably want a different one

The README is unusually direct about who should not be reading it. Under a heading that says you are probably actually looking for one of the following repos, it names three alternatives.

nyc is the IstanbulJS 2.0 command line interface, providing painless coverage support for most popular testing frameworks. babel-plugin-istanbul is a babel plugin for instrumenting your ES2015+ code with Istanbul compatible coverage tracking. And istanbul, in a separate gotwarlost repository, is the legacy 1.0 IstanbulJS interface, and the README says you should now consider using nyc or babel-plugin-istanbul instead.

That is a good sign, not a bad one. Most monorepos try to look like a product. This one tells you plainly that the monorepo is the implementation layer and the products are the packages that consume it, and that the 1.0 interface is legacy and should not be used for anything new.

What the monorepo actually is, is described in the repository description and in the About section. It contains the nuts and bolts utility libraries that facilitate IstanbulJS test coverage, and the README asks the question directly, why a monorepo, and answers it with two reasons. It allows the team to more easily test API changes across coupled modules, for example changes to istanbul-lib-coverage potentially having an effect on istanbul-lib-instrument. And it gives them a centralized repo for discussions about bugs and upcoming features.

The first reason is the one that generalises. The coverage pipeline is a chain, the instrumenter produces the counters, the coverage map merges them, the reporter turns the map into text or lcov, and a change at one link can break another. A monorepo where the tests for all of them run together is the right shape for that kind of coupling.

A lerna build, mocha, nyc and eslint in one pipeline

The root package.json is the clearest description of how the packages are built and tested, and it is a short file.

"scripts": {
  "test": "cross-env NODE_ENV=test nyc mocha --timeout 30000 packages/*/test{,/*}.js",
  "posttest": "eslint .",
  "fix": "eslint . --fix",
  "postinstall": "bash scripts/install.sh"
}

The test script is a single glob across every package, cross-env sets NODE_ENV=test so the same command works on every platform, nyc instruments the tests themselves so the tooling measures itself, mocha runs them with a thirty second timeout, and the path pattern packages/*/test{,/*}.js picks up both the direct test files in each package and the files in their subdirectories.

The posttest hook runs eslint over the whole tree, which means a lint failure fails the build without anyone having to remember a second command. The fix script is the same thing with --fix, and the prettier configuration is right there in the package.json with singleQuote and a tabWidth of 4, and eslint-plugin-prettier and eslint-config-prettier are both in the dev dependencies, so formatting and linting are one operation rather than two that can disagree.

The postinstall hook is bash scripts/install.sh, which is the lerna build the contributing section describes. After checking out, you run npm install and that will run the lerna build. Then npm test in the root directory runs all tests, and to run tests for a single package you cd into that package's folder and run npm test there.

The release tooling is the newer generation. There is a .release-please-manifest.json and a release-please-config.json, so releases are cut by release-please from conventional commits, and the README carries a Conventional Commits 1.0.0 badge, which is the convention the messages follow. The dev dependencies are from that generation too, mocha 7, nyc 15, eslint 6 and prettier pinned to exactly 1.18.2, and the engines field says node >=8.

The coverage pipeline as a set of replaceable pieces

The package names in the repository are the pipeline, and reading them explains what a coverage number is.

istanbul-lib-coverage is the coverage map, the object that holds the file, statement, function and branch counters and can merge counters from several test runs. istanbul-lib-instrument is the instrumenter, the part that rewrites source to insert the counters. istanbul-lib-source-maps is the piece that maps the counters back through transformations so the report points at the original source rather than at compiled output. istanbul-reports is the reporting layer, turning the map into the output formats.

That separation is the reason the monorepo exists, and it is the reason a coverage tool like nyc can work with mocha, jest, tap, tape and ava, all of which appear in the topic list. The test framework does not matter to the coverage machinery, because the framework's job is to run the tests and the instrumenter's job is to have already instrumented the code. The pieces in between, the instrumenter, the map, the reporter, are shared.

The source map package is the one with the subtle job. When a test suite runs against transpiled code, the line numbers in the counters refer to the transpiled output, and a report built from those counters points at the wrong lines of the source the developer is looking at. The source map package is what reconciles the two, and the version history shows it getting maintenance attention, with v5.0.5 on 2024-07-01 and v5.0.6 the next day.

The reports package has its own release line, and it is the one that moved most recently, with v3.2.0 tagged on 2025-08-18. The separate version numbers for separate packages are the practical point, since a consumer pins the one package they use rather than the monorepo.

The monorepo is dated, and the packages are not

The maintenance picture needs to be read carefully, because the two levels of this repository move at different speeds.

The last push to the main branch was on 2026-04-09. The most recent release in the packages is istanbul-reports v3.2.0 from 2025-08-18, and the source maps package is at v5.0.6 from 2024-07-02, preceded by v5.0.5 a day earlier. The release tags are per package rather than for the monorepo as a whole, which is the direct consequence of the release-please setup with a per package manifest.

So the correct statement about maintenance is not that the project is actively developed. The most recent commit to this branch was on 2026-04-09, and the individual packages have been getting releases on their own schedules, with the reports package at v3.2.0 and the source maps package at v5.0.6.

The dependency versions tell the same story from a different angle. mocha at ^7.2.0, nyc at ^15.1.0, eslint at ^6.7.2, prettier pinned to 1.18.2, glob at ^7.1.6, babel-eslint at ^10.0.3 and coveralls at ^3.0.9. These are the versions of the JavaScript tooling ecosystem from around 2019 and 2020, and they are the versions the monorepo's own build runs on.

There is a practical consequence for anyone who wants to work on this code. A dependency tree rooted in eslint 6 and prettier 1.18 will not install cleanly on a current Node without some care, and the tooling conventions in the repository, the lerna build, the.npmrc file, the.nycrc.json for nyc's own configuration, the.eslintrc and.prettierignore, are all from that generation.

The authorisation in the root package.json is ISC, and the license is listed as unknown in the repository listing, so the file in the tree is the one to read for the actual terms of each package.

Where istanbuljs is the wrong thing to reach for

The first wrong case is an ordinary project that wants a coverage number. If you run mocha, jest, tap, tape or ava and you want coverage, you install nyc, or you add babel-plugin-istanbul if you are already using babel. The README says so in the first section a reader sees. Installing the monorepo's internals to get a report is more moving parts than the problem deserves.

The second wrong case is a project that needs coverage of code that is not instrumented. Coverage in this ecosystem comes from rewriting the source before it runs, and anything that is not run through the instrumenter is not measured. That is a limitation of the whole approach rather than of this repository, and a tool that measures from the outside, a profiler or a runtime hook, answers a different question.

The third wrong case is a project on a current toolchain that needs the newest source map handling. The versions here are from an earlier generation of JavaScript, and the source maps package, whose whole job is reconciling transpiled output with original source, is the part most likely to lag behind how a current bundler emits source maps.

The fourth wrong case is a team that expects a maintained umbrella. The README still carries a Travis CI build badge, and the contributing instructions still describe the lerna build and the npm install that triggers it, but the branch itself has not been pushed to since 2026-04-09, so a bug report against the monorepo is going somewhere quieter than it used to.

How it differs from a standalone coverage tool

The comparison worth making is with a single-binary coverage tool, and the difference in approach is that this is a set of libraries rather than a program.

A standalone tool is a program you run. It has a command line, it knows how to find your test files, it knows how to instrument, it runs the tests under a subprocess with the right flags, and it prints a report. The user experience is one command and the internals are hidden.

The istanbuljs packages are the internals. istanbul-lib-instrument is a function that takes source and returns instrumented source. istanbul-lib-coverage is a data structure with a merge operation. istanbul-reports is a set of functions from a map to a formatted string. None of them runs your tests, finds your files, or decides which framework you use.

That difference is what makes the ecosystem work. nyc is the program that ties them together for a test runner, babel-plugin-istanbul is the program that ties them together for a build step, and a coverage tool for a framework that does not exist yet would be another program over the same libraries. When a new test runner appears, the work is a thin wrapper rather than a reimplementation of the instrumenter and the reporter.

The second difference is the surface area for change. A standalone tool has one version to reason about. Here, a change to istanbul-lib-coverage can affect istanbul-lib-instrument, which is exactly the coupling the README gives as the first reason for the monorepo, and the reason there is a shared test command across all packages rather than a per package suite that would not catch the cross effects.

The third difference is the entry point for a user. The README's own guidance is that you are probably looking for nyc or babel-plugin-istanbul, which means the monorepo is the layer that most people never interact with directly. That is the correct outcome for a library layer, and it is also why the maintenance history matters less to most users than the release history of the package they actually depend on.

Editorial conclusion

istanbuljs fits a developer who is building a coverage tool, a reporter or a test runner integration and needs the instrumenter and the coverage map rather than a command line wrapper, and it fits a team that wants to understand what their coverage number actually measures. It does not fit an ordinary project that wants coverage numbers, since nyc or babel-plugin-istanbul are the right dependency there. Before depending on a specific package, check the release tag for that package rather than the monorepo, because the two move independently, with istanbul-reports at v3.2.0 from 2025-08-18 and istanbul-lib-source-maps at v5.0.6 from 2024-07-02, and note that the monorepo itself was last pushed to on 2026-04-09.

Frequently asked questions

Official sources

1. Issues
2. istanbuljs/istanbuljs on GitHub
3. Project website
4. README
5. Releases