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

Use Incremental Compilation and Build Modes

Enable incremental and composite flags to cache type information and speed up subsequent builds.

Use Incremental Compilation and Build Modes

What you'll learn: How to enable TypeScript's incremental compilation to cache type information and dramatically speed up subsequent builds.

What Is Incremental Compilation?

By default, TypeScript type-checks and compiles your entire project from scratch every time you run tsc. This means analyzing every file, resolving every type, and performing complete type-checking—even when you've only changed a single file.

Incremental compilation solves this by caching information about your project's type relationships in a special .tsbuildinfo file. On subsequent builds, TypeScript reads this cache and only reprocesses files that have actually changed (or files that depend on changed files).

Think of it like a photo editing app that saves your edit history—instead of re-applying every filter from scratch, it remembers what you've done and only processes new changes.

How to Enable Incremental Compilation

Add two flags to your tsconfig.json:

{
  "compilerOptions": {
    "incremental": true,
    "composite": true,
    "outDir": "./dist"
  }
}
  • incremental: true — Tells TypeScript to generate and use .tsbuildinfo files
  • composite: true — Required for project references and enforces constraints that make incremental builds reliable (requires declaration: true and explicit rootDir/outDir)

After your first build, you'll see a .tsbuildinfo file appear in your output directory. This contains cached type information and dependency graphs.

Real Build Performance Impact

On a medium-sized codebase:

  • Cold build (no cache): 45 seconds
  • Incremental rebuild (one file changed): 3 seconds

The larger your project, the more dramatic the savings.

Using --build Mode

For projects with composite: true, use tsc --build (or tsc -b) instead of plain tsc:

tsc --build

This mode understands project references and builds dependencies in the correct order, skipping projects that haven't changed.

When to Use Incremental Compilation

  • Monorepos with multiple interconnected packages
  • Large codebases where full rebuilds are slow
  • Development workflows where you're iterating frequently
  • CI/CD pipelines where you can cache the .tsbuildinfo between runs

Key Takeaway: Enabling incremental and composite flags allows TypeScript to cache type information and reuse it across builds, transforming slow full-project type-checks into fast incremental updates that only process what changed.