🌡️ tsc-baseline

Often times when working on a large codebase or joining a new project, you'll be faced with a lot pre-existing type errors. While it's important to fix these errors, practically speaking, it's not realistic to fix them all at once and will likely be done incrementally over time.

tsc-baseline helps you reduce the noise of pre-existing type errors by allowing you to save a baseline of errors and filter them out of future type-checks.

This is especially useful when you're working on a new feature branch and want to focus on the errors introduced by your changes, rather than the errors that were already present in the codebase.

👋 Hello there! Follow me @linesofcode or visit linesofcode.dev for more cool projects like this one.

📡 Install

npm install tsc-baseline

yarn add tsc-baseline

pnpm add tsc-baseline

🚀 Getting Started

First, run a type-check in a project containing errors and save the results to a file. We refer to this file as the baseline.

yarn tsc | yarn tsc-baseline save

Next, make some changes to your codebase that introduce new errors, and run the type-check again. This time, we'll compare the results to the baseline and filter out pre-existing errors.

Running the following command will print out the new errors to the console.

yarn tsc | yarn tsc-baseline check

If you need to explicitly add an error to the baseline, you can do so by copying the error's hash from the console output and running the following command.

yarn tsc-baseline add 1234

When you're done, you can delete the baseline file.

yarn tsc-baseline clear

Scoping the check to changed files

On a large baseline, a pull request can fail on errors it has nothing to do with: a dependency bump or a shared type edit can surface new errors all over the codebase. --changedFiles takes a file listing the paths touched by the current change, one per line, and only lets errors inside those files fail the command. New errors elsewhere are still printed, they just do not change the exit code.

git diff --name-only origin/main... > changed-files.txt
yarn tsc | yarn tsc-baseline check --changedFiles changed-files.txt

A changed path matches an error when the two are equal, or when the changed path ends with the error path, so a list of repo-relative paths still matches when tsc runs from a subdirectory.

Excluding files

Generated code (API clients, compiled output, schema types) produces errors nobody is going to fix by hand, and re-generating it churns the baseline for no reason. --exclude drops those files from both the baseline and the check:

yarn tsc | yarn tsc-baseline save --exclude src/generated/ --exclude "**/*.gen.ts"

• a pattern ending with / excludes a whole directory,
• * matches within a path segment, ** matches across segments,
• anything else matches the path itself or its trailing part.

The patterns are stored in the baseline file, so check reuses them on its own. There is no way to end up comparing a filtered baseline against an unfiltered run.

Paths in the baseline

Paths are recorded relative to the directory tsc-baseline runs from. tsc reports some errors with an absolute path, and spells one out inside the message of others, TS7016 in particular:

Could not find a declaration file for module 'x'.
'/home/you/project/node_modules/x/index.js' implicitly has an 'any' type.

The message is part of the error hash, so an absolute path would tie the baseline to the machine that produced it: the same error reported from another checkout, or from a CI container, would not match and would count as new. The project root is therefore stripped from both the file and the message before hashing, which makes a baseline committed to a repository match everywhere it is checked out.

Error Format Options

You can specify the error format to be used when checking for new errors with the check command. This option affects the output to stderr. By default, the standard error message format is used. However, if you want the output in a GitLab-friendly format, you can use the --error-format option:

• Default Format (human): Shows standard human-readable error messages.
• GitLab Format (gitlab): Outputs errors in a format suitable for GitLab pipelines, making it easier to process in CI/CD workflows.

Example for GitLab format:

yarn tsc | yarn tsc-baseline check --error-format gitlab