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

Profiling Incremental Builds

Learn how to trace incremental builds to see if caching and tsbuildinfo are working effectively.

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 .tsbuildinfo file 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 .tsbuildinfo accidentally?
  • Did you change tsconfig.json options?
  • 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.