Benchmarking TypeScript Type Checking Performance

Introduction

Every TypeScript developer has encountered it: the type checking process is slow. While JavaScript transpilation has many fast alternatives like swc and esbuild, type checking remains a bottleneck as it still requires the tsc TypeScript compiler.

At Spiko, where we heavily rely on strong typing and functional programming with libraries like Effect, type checking performance is crucial. Large codebases with extensive type usage can take several minutes to type check, significantly impacting the development experience and CI velocity.

Understanding TypeScript Performance

Generic type instantiations are one of the most significant contributors to slow type checking. Each time TypeScript needs to resolve a generic type with specific type parameters, it performs complex calculations to ensure type safety. This is called an instantiation.

Let me show you an easy example to understand what an instantiation looks like:

interface Interface<T> {
  value: T;
}

const x: Interface<number> = { value: 10 }; // First instantiation
const y: Interface<string> = { value: "Hello" }; // Second instantiation
const z: Interface<boolean> = { value: true }; // Third instantiation

Here, we have a generic type Interface. By creating 3 variables with 3 versions of this generic type, we are doing 3 instantiations.

The number of instantiations can be used as a metric to evaluate the complexity of Typescript’s type checking process.

How can we monitor type checking performance?

To analyze the number of instantiations and look for bottlenecks, TypeScript provides two powerful tools for type checking performance analysis.

Extended Diagnostics (tsc --extendedDiagnostics)

This command provides detailed metrics about the type checking process. Here’s an sample output from some of our codebase:

$ tsc --extendedDiagnostics

Files:                        3363
Lines of Library:            38813
Lines of Definitions:       379255
Lines of TypeScript:         24612
Lines of JavaScript:             0
Lines of JSON:                   0
Lines of Other:                  0
Identifiers:                462973
Symbols:                    662273
Types:                      268301
Instantiations:            3492575
Memory used:               765956K
Assignability cache size:   126253
Identity cache size:         14395
Subtype cache size:           5266
Strict subtype cache size:    3917
I/O Read time:               0.44s
Parse time:                  0.69s
ResolveModule time:          0.38s
ResolveTypeReference time:   0.00s
ResolveLibrary time:         0.00s
Program time:                1.80s
Bind time:                   0.42s
Check time:                  4.69s
printTime time:              0.00s
Emit time:                   0.00s
Total time:                  6.91s

The command returns a detailed report giving us a lot of information such as number of instantiations, memory usage or type checking duration. These metrics are correlated. The type checking duration is more or less proportional to the number of instantiations. Here, we can see that it is a fairly large project.

Trace Generation (tsc --generateTrace)

To break up the analysis on a per-file basis, TypeScript can generate trace files. We can then analyze these traces using Chrome’s trace viewer by opening chrome://tracing/. Such visualization helps identifying specific type checking bottlenecks.

The TypeScript team also provides a dedicated command line trace analyzer that highlights files with unusually long type checking:

$ tsc --generateTrace tsc-trace && analyze-trace tsc-trace

Hot Spots
└─ Check file /typeCheckTooSlow.ts (1590ms)
   └─ Check deferred node from (line 7, char 43) to (line 16, char 4) (1590ms)
      └─ Check expression from (line 8, char 3) to (line 16, char 4) (1590ms)
         └─ Compare types 171450 and 171523 (1185ms)
            ├─ {"id":171450,"kind":"AnonymousType","location":{"path":"/fileWithIssues.ts","line":16615,"char":38}}
            └─ {"id":171523,"kind":"AnonymousType","location":{"path":"/anotherFileWithIssues.ts","line":529,"char":54}}

Conclusion

Typescript type checking is slow, but should not be too slow. We have covered the main tools that can help you uncover the reason behind unoptimized type checking processes.

In our next article, we will see how we used these tools to optimize our type checking process at Spiko, and how we actually made it 20% faster.