TypeScript Reference ยท Concepts and Comparisons
TypeScript compiler performance
How to find and fix slow TypeScript builds and editors: skipLibCheck, incremental builds, project references, simpler types and diagnostics flags.
A TypeScript build has three costs: reading files and resolving modules, checking types, and emitting output. In small projects all three are instant. In large ones the checker dominates, and a single expensive type can slow both tsc and the editor for everyone. Performance work means measuring first, then choosing the cheapest fix.
Start with tsc --extendedDiagnostics. It prints how many files, lines, types and instantiations the program has and how long each phase took. If "Check time" dwarfs everything else, you have a type-complexity problem; if "I/O read" or file count is huge, you are including too much.
tsc --noEmit --extendedDiagnostics tsc --noEmit --generateTrace ./trace-output
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Fixes in order of payoff
- Skip checking
.d.tsfiles you do not own. skipLibCheck avoids re-checking every package's declarations. - Do not include more than you need. A broad
includeor a missingexcludecan pull in build output, test fixtures andnode_modulesJavaScript. Check withtsc --listFiles. - Limit automatic
@typesloading. types lists exactly which global type packages to load. - Build incrementally. incremental stores a
.tsbuildinfofile so unchanged files are not re-checked. - Split big programs with project references and composite, then build with
tsc --build. Each project is checked and cached separately. - Simplify types the trace points at. Open the trace in a viewer such as
chrome://tracingand look for longcheckSourceFileorstructuredTypeRelatedToevents. - Use the native compiler. TypeScript 7 is written in Go and is much faster at the same work; see TypeScript 7 native compiler.
What makes types slow
- Recursive conditional types over large unions or deep objects.
- Big unions (thousands of members) combined with mapped or template literal types, which multiply.
- Long intersection chains used instead of
interface extends. - Generic functions with many overloads and heavy inference at every call site.
- Return types left to inference in exported functions, which force the checker to analyze the body wherever the function is used. Explicit annotations on public APIs help.
Usage notes
- Measure before and after. Run the same command three times; the first run may be cold.
- Separate type checking from emitting. Bundlers such as esbuild and Vite strip types without checking, so
tsc --noEmitcan run in parallel in CI. - Editor slowness is not always
tscslowness. A huge file or a plugin can be the cause; the TS Server log shows the time per request. - Tail recursion in conditional types is optimized up to a depth limit, but deeply nested ones still hit "excessively deep" errors such as TS2589; see TS2589.
- Do not trade away safety lightly. Replacing a precise type with
anymakes the build faster and the program worse.