Course contentsShow
← TypeScript
Lesson 1727 of 1,79639. TypeScript PerformanceFree lesson

The --generateTrace Flag

Enable --generateTrace to produce a detailed trace file for analysis with chrome://tracing or @typescript/analyze-trace.

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:

  1. chrome://tracing — Open Chrome, navigate to chrome://tracing, and load the trace.*.json file. You'll see a flame graph showing exactly where time is spent.

  2. @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.