typescript-coverage-report: measuring how much of your TypeScript is actually typed

TypeScript will not tell you how much of your code is typed

TypeScript accepts any without complaint, and nothing in the compiler flags a file that leans on it. That blind spot is the problem alexcanessa/typescript-coverage-report sets out to close. The project describes itself as a Node command line tool for generating TypeScript coverage reports, and it frames the gap in ecosystem terms: the README calls it a missing type coverage reporting tool that exists in the Flow ecosystem. The comparison is not decorative. The documentation says the work is strongly inspired by flow-coverage-report, and that the underlying data is generated by type-coverage. So the audience is engineers who already think of type coverage the way Flow developers do, and who want the same kind of report for a TypeScript codebase. It measures how much of the source is genuinely typed rather than silently falling back to any.

type-coverage-core does the counting, the CLI shapes what you read

Mechanically this package is a thin layer over type-coverage-core, which sits in the dependency list next to chalk, cli-table3 and commander. The library counts the uncovered positions; this package turns those counts into output you can read in a terminal or publish as a browsable report. That split decides what you can influence. The counting rules belong to type-coverage-core, while everything you can tune lives in the option list exposed by the CLI. A plain run uses the text, html and json reporters, so you get a terminal table plus a report directory named coverage-ts. Two more reporters are named in the options table, lcov and cobertura, which is the route into an existing CI dashboard. The published package includes dist and assets, and the binary entry points at dist/bin/typescript-coverage-report.js.

Adding the script to package.json and choosing a threshold

The README advises installing the package as a project dev dependency and creating a script in package.json, rather than installing it globally. The yarn and npm forms both attach a dev flag, so nothing enters your production dependency tree:

$ yarn add --dev typescript-coverage-report

$ npm install --save-dev typescript-coverage-report

With the package in place, add a script entry so the binary is reachable through your package manager:

"scripts": {
  "ts-coverage": "typescript-coverage-report"
}

Then run it with whichever package manager the project already uses:

$ yarn ts-coverage

The default minimum threshold is 80 percent. A single run can raise that bar with the threshold option:

$ yarn ts-coverage --threshold=99

Alternatively, the type-coverage configuration block in package.json carries the same setting, which keeps the floor next to the rest of the project configuration:

"typeCoverage": {
  "atLeast": 90
}

A default run leaves a report in coverage-ts, illustrated in the documentation with a terminal table, a summary page and a details page, and a published example report is linked from the README.

The option list is where the policy of the tool actually lives

Twenty-eight documented options do more than change cosmetics. The output directory option relocates the report, and the project option points the run at a specific tsconfig, which matters in a monorepo where each package has its own. The strict option switches the underlying check into strict mode, and debug prints more about the run. Caching is off by default and can be switched on with the cache flag, paired with a cache directory option that says where to keep the cached type check result. File selection is handled by the ignore-files glob option, which is repeatable and takes patterns such as demo1/*.ts, and by the not-only-in-cwd flag, which decides whether files outside the working directory are included. Config files are picked up automatically, and the config option overrides that search. Two flags change what a run means rather than what it looks like: allow-empty succeeds when no files were analysed, and respect-gitignore excludes files that git ignores.

Every ignore flag lowers the score, and the defaults do not lower it

The option table contains a dense cluster of flags that each subtract something from the denominator of uncovered positions. There is a flag to ignore any in catch clause variables, one to allow writes to variables with implicit any types, and separate switches for nested anys such as Promise<any>, for assertions written as foo as string, for assertions written as <string>foo, for non-null assertions written as foo!, for the Object type, and for the empty type {}. All of them default to false. The point worth making is that a team can quietly turn on a dozen of these and end up with a near perfect number that says very little about the code. Two flags push the other way. Reporting semantic errors as uncovered folds TypeScript compile errors into the count, and the report-unused-ignore flag catches type-coverage:ignore-line comments that suppress nothing, which is a useful guard against leftover suppression comments drifting through the codebase.

Failing a build on a regression rather than on a number

A threshold alone tells you where you are, not whether you moved. The compare option accepts the path of an earlier report and exits with code 3 if any file decreased, which is a per file comparison rather than a project average. That matters because a project wide number can stay flat while a single heavily used module quietly loses its types. The history-file option is the other half of the same idea: it appends the totals of the current run to a JSON file, giving you a series of numbers to diff across builds. Together these two options are what make the tool usable as a gate. The trailing arguments rule completes the picture, since any arguments after the options are treated as the only files to check, which is exactly what a staged-files workflow needs:

$ typescript-coverage-report src/one.ts src/two.ts

A Node 22 floor, a recent release trail, and an MIT licence

The package manifest sets engines to node >=22.12.0, so an older runtime will refuse the install rather than fail halfway through a report. That floor is the single most important upgrade cost to check before adopting this in a legacy service. The version history shows three tagged releases in late September 2026, namely 2.1.0 on 2026-09-24, 2.1.1 on 2026-09-26 and 2.1.2 on 2026-09-28, and the last push to the repository was on 2026-10-01. Release automation is present at the root of the project, with release-please-config.json and .release-please-manifest.json alongside a CHANGELOG.md and a MIGRATING.md file for people crossing a major version boundary. The project is released under the MIT licence, which permits commercial use and modification without any fee, though the licence text itself is the authoritative statement of the obligations.

Editorial conclusion

Adopt typescript-coverage-report if your team already enforces type discipline and wants a single number for uncovered positions, and wire the threshold into an existing script rather than a global install. Skip it if you are looking for a tool that locates untyped code for you, since the counting is delegated to type-coverage-core and the ignore flags can make the score look better than the code is. Before trusting a first run, check the threshold against a known file, confirm that your tsconfig path matches what the project expects, and read the exit code from a --compare run in CI.

Frequently asked questions

Official sources

1. alexcanessa/typescript-coverage-report on GitHub
2. Issues
3. License: MIT
4. README
5. Releases