Profiling Incremental Builds
You'll learn how to trace incremental builds to verify that caching and .tsbuildinfo are working as intended.
When you enable --incremental, TypeScript generates a .tsbuildinfo file that stores metadata about your previous compilation. This allows TypeScript to skip re-checking unchanged files on subsequent builds. But how do you know it's actually working?
Why Profiling Matters
Just enabling incremental compilation doesn't guarantee faster builds. You need to verify:
- Is the
.tsbuildinfofile being created and reused? - Are unchanged files actually being skipped?
- Are you accidentally invalidating the cache?
Think of incremental builds like a chef's prep station: if ingredients from yesterday are still fresh, you don't chop them again. But if someone throws them away between shifts, you're back to square one.
Profiling Your Incremental Build
Use the --diagnostics flag combined with --incremental:
tsc --incremental --diagnostics
On the first run, you'll see full compilation times. The .tsbuildinfo file is created.
On the second run (without changing files), look for dramatically reduced times. The diagnostics output shows you cache hits.
For deeper analysis, combine with --extendedDiagnostics:
tsc --incremental --extendedDiagnostics
This reveals file-level caching details and helps you spot files that are unexpectedly being rechecked.
Common Cache Invalidation Culprits
If your incremental builds aren't fast, check:
- Are you deleting
.tsbuildinfoaccidentally? - Did you change
tsconfig.jsonoptions? - Are file timestamps changing even when content doesn't (common in Docker/CI)?
Key Takeaway: Use --diagnostics and --extendedDiagnostics with your incremental builds to verify that TypeScript is actually reusing cached type information and not silently recompiling everything.