Type Checking Performance
In this page:
Core Concept
TypeScript's type checker can slow down noticeably on large codebases, especially with deeply nested generics, huge union types, or overly broad include globs that pull in files that don't actually need checking.
Example: Core Concept
// Deeply nested generics and huge unions slow down the type checker.
console.log("Large codebases can hit real type-checking performance limits");Basic Setup
A basic diagnostic setup runs tsc --extendedDiagnostics (or --generateTrace) to see exactly which files and language features are consuming the most check time, rather than guessing at the bottleneck.
Example: Basic Setup
// tsc --extendedDiagnostics
console.log("extendedDiagnostics shows exactly what's consuming check time");Typed Example
A typed example of a common slowdown: a union type with hundreds of string literal members forces the compiler to compare every member on each assignment check, which is measurably slower than a narrower type or an enum.
Example: Typed Example
type Status = "a" | "b" | "c"; // a 500-member union would be much slower
function check(s: Status) { return s; }
console.log(check("a"));Project Usage
In a real project, splitting a monolith into project references (each independently cached) plus enabling "skipLibCheck": true are usually the two highest-impact changes for cutting overall check time.
Example: Project Usage
// tsconfig.json: { "compilerOptions": { "skipLibCheck": true } }
console.log("skipLibCheck plus project references are the biggest speed wins");Best Practices
Avoid overly clever recursive conditional types in hot-path type definitions — they're a common, hard-to-spot source of exponential type-checking time on otherwise reasonably-sized codebases.
Example: Best Practices
// Avoid deeply recursive conditional types in hot-path type definitions.
type Depth1<T> = T extends string ? "string" : "other";
console.log("Recursive conditional types can cause exponential check time");Chapter Quiz — Complete all 5 topics to unlock
0/5 topics done
Complete these topics first: