Using @typescript/analyze-trace CLI
What you'll learn: How to run the @typescript/analyze-trace command-line tool to automatically identify the slowest types and performance bottlenecks in your TypeScript project.
What Is @typescript/analyze-trace?
When you generate a trace file with --generateTrace, you get a detailed JSON log of everything the TypeScript compiler did. But manually reading through thousands of trace entries in Chrome DevTools is tedious and error-prone.
The @typescript/analyze-trace package is a CLI tool from the TypeScript team that automatically processes trace files and gives you a human-readable summary of the worst performance offenders. Think of it as having an expert analyze your compile performance and point directly at the problems.
Installing and Running the Tool
First, install it globally or use npx:
npm install -g @typescript/analyze-trace
# or
npx @typescript/analyze-trace
After you've generated a trace file:
tsc --generateTrace trace_output
Run the analyzer on that directory:
analyze-trace trace_output
What the Output Shows You
The tool produces a summary with sections like:
- Top types by check time: Which types took the longest to check
- Top types by instantiation count: Which types were instantiated most frequently
- Slowest files: Which source files consumed the most compiler time
- Bottleneck hotspots: Specific type operations causing delays
Each entry typically shows the type name, the file location, and timing metrics. You'll see output like "Type DeepPartial<MyHugeType> took 2,300ms across 1,500 instantiations."
Why This Matters
Instead of guessing which complex types are slowing your build, analyze-trace tells you exactly where to focus your optimization efforts. You might discover that one deeply nested conditional type or a massive union is responsible for 80% of your compile time.
Key Takeaway: The @typescript/analyze-trace CLI automatically processes trace files and highlights the top type-checking bottlenecks, giving you actionable insights to speed up your builds without manual trace file analysis.