TypeScript Diagnostics: Reading the Numbers

Before you can fix TypeScript performance, you have to know what's actually slow. The good news: TypeScript ships its own diagnostic tools. The bad news: most people don't know they exist until they're deep in a multi-hour debugging session.

There are four flags I reach for, in roughly this order.

--extendedDiagnostics

This is the first stop. It adds a timing and memory breakdown to your normal type check output:

You'll see output like:

The numbers that matter most:

• Files: If this is dramatically higher than you expect, something is pulling in files you didn't intend. This is where barrel file problems show up.
• Instantiations: The number of times TypeScript had to instantiate generic types. High instantiation counts are the fingerprint of complex conditional types.
• Memory used: If this is over 512MB, you're in trouble on standard machines. Over 1GB and you'll start seeing the TypeScript server crash.

Running this on CI before and after a change gives you a baseline to catch regressions early.

--listFiles

When the Files count in --extendedDiagnostics is higher than expected, this flag tells you exactly which files TypeScript is checking:

The output is a flat list of every file included in the program. Pipe it somewhere useful:

If that returns anything above zero with skipLibCheck: false, you're doing unnecessary work. More commonly, --listFiles reveals that your tsconfig.json root is pulling in test files, scripts directories, or entire packages you didn't mean to include.

The fix is almost always tightening the include array in your tsconfig.json:

Not ".". Not "**/*". Specific directories.

--explainFiles

--listFiles tells you what's included. --explainFiles tells you why:

The output looks like:

This is invaluable for the "I don't know why TypeScript is including this" problem. You'll often find that a single import somewhere in your codebase is pulling in a giant type definition file you didn't expect — and this tells you exactly which import is responsible.

It's also how you diagnose barrel file cascades. When you see a single component file that has a chain of 40 files below it in --explainFiles, that's a barrel file pulling in the entire module graph.

--generateTrace

The most powerful tool, and the most involved. This generates a performance trace file compatible with Chrome DevTools:

It creates two files in the specified directory: trace.json and types.json.

To read it:

1. Open Chrome and navigate to chrome://tracing
2. Load the trace.json file
3. Look at the timeline

You'll see a waterfall breakdown of every phase TypeScript went through — which files took longest to parse, which types took longest to instantiate, which modules took longest to resolve.

The types.json file is a separate view: a catalogue of every type TypeScript constructed during the check, with its ID and how it was built. When you have a type that's being instantiated thousands of times, this is how you find it.

It's genuinely the most useful tool for diagnosing deep type complexity issues. The output format is the same one used for profiling JavaScript in Chrome DevTools — so if you've read flame charts before, this is immediately familiar.

The Diagnostic Workflow

Here's how I use these in practice:

1. Establish a baseline: Run --extendedDiagnostics on main, save the numbers
2. Identify the problem category:
   • High file count → --listFiles then --explainFiles
   • High instantiation count → --generateTrace
   • High memory → usually barrel files or complex generics; check both
3. Make a targeted change (not three changes at once)
4. Measure again with --extendedDiagnostics

The temptation is to guess at the problem and try a bunch of fixes simultaneously. That makes it impossible to know what actually helped. One change, measure, repeat.

The diagnostic tools work the same way whether the slowdown is in local type checking or CI — which is useful, because CI is often where the problem is worst and where it's hardest to debug interactively.