The --generateTrace Flag
What you'll learn: How to enable --generateTrace to produce a detailed trace file that reveals exactly what TypeScript is doing during compilation, perfect for diagnosing performance bottlenecks.
What Is --generateTrace?
When TypeScript compilation feels slow, you need data—not guesses. The --generateTrace flag tells the compiler to record every action it takes during type checking and emit: which files it processes, how long each operation takes, what types it instantiates, and where it spends its time.
Think of it like a flight recorder for your TypeScript build. Instead of crashing mysteriously slow, you get a black box you can analyze.
Enabling the Flag
Run TypeScript with the trace flag and specify an output directory:
tsc --generateTrace trace-output
This creates a folder (trace-output/) filled with JSON files containing timing information, memory snapshots, and operation logs.
Analyzing the Trace
The raw JSON isn't human-friendly. You have two main tools:
-
chrome://tracing — Open Chrome, navigate to
chrome://tracing, and load thetrace.*.jsonfile. You'll see a flame graph showing exactly where time is spent. -
@typescript/analyze-trace — A TypeScript team tool that parses the trace and gives you a ranked list of the slowest operations.
Install and run:
npx @typescript/analyze-trace trace-output
You'll get output like:
- Which types took longest to instantiate
- Which files caused the most work
- Hotspots in conditional type evaluation
When to Use This
You've already used --extendedDiagnostics and identified that something is slow—now you need to know what exactly. This is your surgical tool for finding the recursive type that's exploding, the union that's distributing wildly, or the mapped type iterating over thousands of keys.
Key Takeaway: The --generateTrace flag generates a detailed performance trace that you can visualize in chrome://tracing or analyze with @typescript/analyze-trace to pinpoint the exact source of slow type checking.