Incremental Compilation
In this page:
{
"compilerOptions": {
"incremental": true,
"tsBuildInfoFile": "./.tsbuildinfo"
}
}Core Concept
Incremental compilation has tsc save a .tsbuildinfo file recording which files were checked and what they depend on, so a later compile only re-checks files that actually changed instead of the entire project from scratch.
Example: Core Concept
// tsconfig.json: { "compilerOptions": { "incremental": true } }
// Produces a .tsbuildinfo file tracking what's already been checked.
console.log("Incremental builds only re-check files that actually changed");Basic Setup
Enabling it is a single tsconfig.json flag: "incremental": true (or it's implied automatically when "composite": true is set for project references).
Example: Basic Setup
// tsconfig.json
// { "compilerOptions": { "incremental": true, "tsBuildInfoFile": "./.tsbuildinfo" } }
console.log("A single flag enables incremental compilation");Typed Example
A typed example: on a large project, the first tsc run might take 20 seconds, but a second run after editing one file completes in under a second, since only that file and its dependents get re-type-checked.
Example: Typed Example
// First tsc run: 20s. Edit one file, run again: under 1s.
console.log("Only the changed file and its dependents get re-checked");Project Usage
In a real project, incremental compilation combined with a watch mode (tsc --watch) is what makes a large codebase's edit-save-recheck loop feel instant instead of forcing a multi-second wait after every keystroke.
Example: Project Usage
// tsc --watch + incremental: true makes the edit-save loop feel instant
console.log("Watch mode plus incremental builds speeds up large codebases");Best Practices
Commit .tsbuildinfo to version control only if your CI setup can reliably restore it between runs; otherwise exclude it from git and let each fresh CI run pay the one-time full-compile cost.
Example: Best Practices
// .gitignore: .tsbuildinfo (unless CI can reliably cache it)
console.log("Only commit .tsbuildinfo if your CI can restore it between runs");- Deleting or committing the
.tsbuildinfofile, so incremental builds start over or use stale data. - Expecting
incrementalto speed up the first build, when only later builds benefit. - Using
--noEmitwithincrementalwithout settingtsBuildInfoFile, in versions where it is needed.
Chapter Quiz — Complete all 5 topics to unlock
0/5 topics done
Complete these topics first: