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.tsbuildinfofilescomposite: true— Required for project references and enforces constraints that make incremental builds reliable (requiresdeclaration: trueand explicitrootDir/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
.tsbuildinfobetween 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.