TypeScript Coverage Report

Node command line tool for generating TypeScript coverage reports ✨

Overview

This package fills the gap of a missing type coverage reporting tool which is present in the Flow ecosystem, strongly inspired by the amazing work done by flow-coverage-report and using data generated by type-coverage.

See an example of the coverage report.

Background

To learn more about the reasoning behind this project and its roadmap, please refer to the following article: How I built a TS coverage report tool

Install

typescript-coverage-report can be installed locally or globally.

Users are advised to install it as a project (dev) dependency and create a script in package.json.

$ yarn add --dev typescript-coverage-report

# OR

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

Usage

If installed locally, add the following to the scripts section of package.json.

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

Then run:

$ yarn ts-coverage

# OR

$ npm run ts-coverage

To set the minimum threshold (80% by default), use the --threshold option.

$ yarn ts-coverage --threshold=99

As an alternative, options may be provided through the type-coverage configuration, specified in package.json.

"typeCoverage": {
  "atLeast": 90
}

Options

The CLI accepts a list of arguments:

Any trailing arguments are treated as the only files to check, which is useful with tools like lint-staged:

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

Configuration file

Options can live in a config file instead of being repeated on the command line. Any of these is picked up automatically, in order:

.typecoveragerc
.typecoveragerc.json
typescript-coverage-report.config.json

{
  "atLeast": 90,
  "outputDir": "coverage-ts",
  "reporters": ["text", "html", "lcov"],
  "ignoreFiles": ["vendor/**", "generated/**"],
  "strict": true
}

Or point at one explicitly with --config ./config/coverage.json.

The typeCoverage block in package.json still works and is unchanged. A dedicated config file takes precedence over it, and only the first file found is used — they are not merged, so it is never ambiguous where a setting came from.

Precedence is defaults → config file → command line flags, so a flag always wins.

Using it in CI

The CLI exits 2 when coverage is below the threshold, so gating a build needs nothing more than running it:

- run: npx typescript-coverage-report --threshold 90

For CI systems that render coverage themselves, pick the reporters you want with --reporters. Running only the artifact you need also skips the terminal table, which on a large project takes a while to print:

# Codecov, Coveralls, SonarQube, GitHub annotations
$ typescript-coverage-report --reporters lcov --threshold 90

# Azure Pipelines, Jenkins, GitLab
$ typescript-coverage-report --reporters cobertura --threshold 90

# everything, including the browsable HTML report
$ typescript-coverage-report --reporters text,html,json,lcov,cobertura

The default stays text,html,json, so upgrading changes nothing unless you ask it to.

Per-file coverage deltas

Uploading lcov.info is what lets Codecov, Coveralls or SonarQube tell you that a pull request lowered coverage on a particular file — this tool does not need to know anything about git for that to work:

- run: npx typescript-coverage-report --reporters lcov --threshold 90
- uses: codecov/codecov-action@v7
  with:
    files: coverage-ts/lcov.info

Monorepos and project references

A root tsconfig.json that only lists references compiles nothing itself, and project references are not followed. Running from such a root used to report 100% over zero files, which silently satisfied any threshold.

It now fails instead:

No files were analysed, so there is nothing to report.

Point --project at a package's own tsconfig, and run it once per package:

$ typescript-coverage-report --project packages/api/tsconfig.json

Pass --allow-empty if an empty result really is expected.

Ignoring files git ignores

--respect-gitignore drops files that git ignores, even when your tsconfig.json compiles them:

$ typescript-coverage-report --respect-gitignore

This is off by default, because the report is meant to reflect what TypeScript actually compiled. It is useful when tsconfig.json has no exclude and a build directory ends up in the program.

git check-ignore is asked rather than .gitignore being parsed, so negation, nested .gitignore files, precedence and directory rules all behave exactly as git does. Outside a git repository the flag warns and changes nothing, rather than silently dropping files.

Failing when a file gets worse

--compare checks this run against an earlier report and exits 3 if any individual file's coverage dropped — even when the overall threshold still passes.

# on the base branch
- run: npx typescript-coverage-report --reporters json --outputDir base

# on the pull request
- run: npx typescript-coverage-report --reporters json --compare base/typescript-coverage.json

Type coverage went from 92.31% to 88.46%.

1 file decreased:
  src/parser.ts: 100.00% -> 62.50% (-37.50)

Percentages are compared rather than raw counts, so adding covered code to a file is never a regression. Files that are new since the baseline are ignored — the overall --threshold is what guards those.

Exit codes:

3 is checked before 2, so a run that is both below threshold and regressed reports the regression.

The tool deliberately knows nothing about git. You supply the baseline however suits you — a base-branch checkout, a stored CI artifact, or a committed file — which keeps this usable outside CI too.

How line coverage is derived

Type coverage counts identifiers, but lcov and Cobertura are line-based. A line is reported as covered when it contains no uncovered identifier, and uncovered when it contains at least one. Blank and comment-only lines are left out of the denominator.

This means the line rate in those artifacts is not identical to the identifier percentage in the terminal table. The identifier-level numbers are the authoritative ones, and they are what the exit code and typescript-coverage.json use.

Tracking coverage over time

--history-file appends each run's totals to a JSON array, which is useful for charting a trend or for a simple "did it go down" check:

$ typescript-coverage-report --history-file coverage-history.json

[
  {
    "timestamp": "2026-09-24T13:26:31.915Z",
    "percentage": 76.1905,
    "total": 21,
    "covered": 16,
    "uncovered": 5
  }
]

Migrating to 2.0

2.0 is mostly a repair release: 1.1.0 and 1.1.1 were broken on npm, and this is the first version in eighteen months that installs and runs correctly. If you are pinned to ^0.8.0 because of that, this is the upgrade that unpins you.

See MIGRATING.md for the detail on each, including two that are worth checking even though they look cosmetic: --strict false used to turn strict mode on, and an invalid --threshold used to exit 0 however low the coverage was.

Maintainers

@alexcanessa

Contributing

Feel free to dive in! Open an issue or submit a pull request.

See CONTRIBUTING.md for how to get set up, what the checks are, and how commit messages and releases work.

This project follows the Contributor Covenant Code of Conduct.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!

Licence

MIT @ Alessandro Canessa