The --diagnostics Flag for Quick Summaries
You'll learn how to use TypeScript's --diagnostics flag to get instant, high-level performance metrics without diving into complex trace analysis.
What This Flag Does
When you're trying to understand why your TypeScript compilation feels slow, the --diagnostics flag is your first stop. Think of it like checking your car's dashboard: you get the essentials—speed, fuel, temperature—without lifting the hood.
Running tsc with --diagnostics appends a simple summary to your build output showing three critical metrics:
- Files processed: How many files TypeScript examined
- Lines of code: Total lines across all those files
- Memory usage: Peak memory consumption during compilation
- Total compile time: Wall-clock time from start to finish
This is perfect for quick health checks. You can spot obvious problems—like accidentally including thousands of node_modules files—without the overhead of generating full trace files.
How It Differs from Other Tools
Unlike --extendedDiagnostics (which dumps overwhelming detail) or --generateTrace (which requires analysis tools), --diagnostics gives you a one-line answer to "Is compilation slow, and roughly why?"
Running It
tsc --diagnostics
The output appears at the end of your compilation:
Files: 327
Lines: 145821
Nodes: 523442
Identifiers: 178234
Symbols: 94532
Types: 28764
Memory used: 189234K
I/O read: 0.05s
I/O write: 0.01s
Parse time: 0.82s
Bind time: 0.34s
Check time: 2.15s
Emit time: 0.21s
Total time: 3.57s
At a glance, you can see that type checking (Check time) dominates this build—a common pattern worth investigating if it's unexpectedly high.
When to Use This Flag
Use --diagnostics when you want to:
- Confirm whether compilation is actually slow
- Compare build times after configuration changes
- Get a quick baseline before deeper profiling
- Monitor build metrics in CI logs
Key Takeaway: The --diagnostics flag provides an instant, readable performance summary showing file counts, memory usage, and compile time phases—perfect for quick assessments without trace file complexity.