Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
tsc --noEmit --extendedDiagnostics
tsc --noEmit --generateTrace ./trace-output

Try it

TypeScript Expensive versus cheap types

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.

TypeScript Interfaces cache better than big intersections

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

  1. Skip checking .d.ts files you do not own. skipLibCheck avoids re-checking every package's declarations.
  2. Do not include more than you need. A broad include or a missing exclude can pull in build output, test fixtures and node_modules JavaScript. Check with tsc --listFiles.
  3. Limit automatic @types loading. types lists exactly which global type packages to load.
  4. Build incrementally. incremental stores a .tsbuildinfo file so unchanged files are not re-checked.
  5. Split big programs with project references and composite, then build with tsc --build. Each project is checked and cached separately.
  6. Simplify types the trace points at. Open the trace in a viewer such as chrome://tracing and look for long checkSourceFile or structuredTypeRelatedTo events.
  7. 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 --noEmit can run in parallel in CI.
  • Editor slowness is not always tsc slowness. 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 any makes the build faster and the program worse.