TypeScript Coverage Report

1.1.1 · active · verified Tue Apr 21

typescript-coverage-report is a Node.js command-line tool designed to generate comprehensive type coverage reports for TypeScript projects. It visually highlights areas in the codebase that lack strong typing, helping developers track progress in TypeScript adoption or maintain strict type discipline. Currently at version 1.1.1, the package seems to follow an ad-hoc release cadence, with previous minor versions addressing specific TypeScript compatibility issues and feature enhancements. Its key differentiator is being strongly inspired by and filling a similar niche to `flow-coverage-report` in the Flow ecosystem, leveraging data from the `type-coverage` package to analyze `any` usage.

Common errors

```
Maximum call stack size exceeded
```
cause This error was a known bug in older versions (pre-0.5.1) of `typescript-coverage-report`, often triggered by analyzing large projects or specific complex code structures.

fix Upgrade `typescript-coverage-report` to version 0.5.1 or newer to resolve this bug. `npm install typescript-coverage-report@latest`
```
Coverage threshold of XX% not met (found YY%)
```
cause The calculated type coverage percentage (YY%) for your project is below the minimum threshold (XX%) configured via `--threshold` or `typeCoverage.atLeast` in `package.json`.

fix Increase the type coverage in your project by adding more explicit type annotations, or adjust the `--threshold` CLI option or `typeCoverage.atLeast` value in `package.json` to a lower, more realistic percentage.
```
`typescript-coverage-report` wrongly reports 100% of coverage in almost everything.
```
cause This can happen if the tool is not correctly configured to analyze all relevant files, or if `tsconfig.json` exclusions are too broad, leading to an incorrect perception of full coverage for partially typed files.

fix Verify your `tsconfig.json`'s `include` and `exclude` paths. Ensure the `--project` option is pointing to the correct `tsconfig.json`. Check that the `type-coverage` configuration within `package.json` (which `typescript-coverage-report` uses) is set up to analyze all desired files and not implicitly ignoring types.
```
Syntax highlighter doesn't support emojis
```
cause A known bug in the internal code highlighter used by the generated HTML report does not correctly render or may break with emojis present in source code comments or strings.

fix This is a minor display bug in the HTML report and does not affect the correctness of the coverage calculation. Avoid using emojis directly in your code if you rely on the HTML report's highlighting for these specific lines. There is no direct user fix beyond avoiding the problematic characters.

Warnings

gotcha The `typescript-coverage-report` tool has historically encountered compatibility issues with newer TypeScript versions shortly after their release (e.g., fixes for TS 4.x and 4.4 were needed in previous versions). While its `peerDependencies` are broad (2 || 3 || 4 || 5), new major TypeScript releases might introduce breaking changes to internal APIs that the tool relies on, potentially causing unexpected failures until `typescript-coverage-report` is updated.
Fix: Before upgrading to a brand new major TypeScript version, check the `typescript-coverage-report` GitHub issues and releases for any known compatibility problems. Consider pinning your TypeScript version if encountering issues with the latest release.
gotcha The tool deletes the specified output directory (`coverage-ts` by default) before generating the new report. If you have custom files or other important data stored within this directory, they will be irrevocably lost without a warning.
Fix: Always specify an `--outputDir` (or `outputDir` in `package.json`) that is exclusively used by `typescript-coverage-report` and contains no other critical files. Consider committing generated reports to version control only if necessary, and ensure a `.gitignore` entry for the output directory.
gotcha Options can be configured via CLI flags (e.g., `--threshold`) or through the `typeCoverage` section in `package.json` (e.g., `"atLeast": 90`). In most CLI tools, command-line arguments take precedence over file-based configurations. If conflicting values are provided, the CLI flag's value will likely override the `package.json` setting, which can lead to unexpected behavior.
Fix: Choose one primary method for configuration (either CLI flags or `package.json`) and stick to it to avoid confusion. If both are used, be aware that CLI flags typically override `package.json` settings for the same option.
gotcha If your project's `tsconfig.json` is not located in the current working directory where the command is run, or if you have multiple `tsconfig.json` files, the tool may not correctly identify the project context. This can lead to an incomplete or inaccurate coverage report.
Fix: Always explicitly specify the path to your `tsconfig.json` file using the `--project` CLI option, for example: `typescript-coverage-report --project ./path/to/my/tsconfig.json`.

Install

npm install typescript-coverage-report npm
yarn add typescript-coverage-report yarn
pnpm add typescript-coverage-report pnpm

Imports

CLI Execution
wrong:
```
import { generateReport } from 'typescript-coverage-report'
```
correct:
```
npx typescript-coverage-report
```
This package is primarily a command-line interface (CLI) tool. It is not designed for direct programmatic import of its functions. The `npx` command executes the locally installed binary.
CLI Execution (via package.json script)
wrong:
```
Attempting to run `typescript-coverage-report` directly if not globally installed or in PATH.
```
correct:
```
"scripts": { "ts-coverage": "typescript-coverage-report" }` then `npm run ts-coverage`
```
For local installations, adding a script to `package.json` is the recommended way to invoke the CLI, making it accessible via `npm run` or `yarn`.
Configuration (package.json)
wrong:
```
Placing `typeCoverage` options directly at the root of `package.json` or under an incorrect key.
```
correct:
```
{
  "typeCoverage": {
    "atLeast": 90,
    "threshold": 90
  }
}
```
Configuration options, such as the minimum coverage threshold, can be defined within `package.json` under the `typeCoverage` key, which the CLI tool will then read.

Quickstart

This quickstart demonstrates how to install `typescript-coverage-report`, configure a `package.json` script, and run the CLI tool to generate an HTML type coverage report for a basic TypeScript project, setting a custom threshold and output directory.

{
  "name": "my-ts-project",
  "version": "1.0.0",
  "description": "A sample TypeScript project",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "ts-coverage": "typescript-coverage-report --threshold=95 --outputDir=./html-coverage"
  },
  "keywords": [],
  "author": "",
  "license": "MIT",
  "devDependencies": {
    "typescript": "^5.0.0",
    "typescript-coverage-report": "^1.1.1"
  }
}

// Create a tsconfig.json file in the root:
// {
//   "compilerOptions": {
//     "target": "ES2020",
//     "module": "CommonJS",
//     "strict": true,
//     "esModuleInterop": true,
//     "skipLibCheck": true,
//     "forceConsistentCasingInFileNames": true,
//     "outDir": "./dist"
//   },
//   "include": ["src/**/*.ts"]
// }

// Create a sample TypeScript file (e.g., src/index.ts):
// export function add(a: number, b: number): number {
//   return a + b;
// }

// export function subtract(a: any, b: number) {
//   // 'a' is implicitly 'any', reducing type coverage
//   return a - b;
// }

// Now run the coverage report:
// npm install
// npm run ts-coverage

view raw JSON →