Shorten repeated local builds
Large applications
TypeScript · Const
incremental
Enables TypeScript to persist project-graph information between compilations. Later builds can reuse that information to reduce type-checking and emit work.
- Since
- 3.4
How it works
When enabled, TypeScript persists information about the project graph from the previous compilation. Later compilations use that cache to identify the least expensive type-checking and emit work, while the cache remains build-time data rather than runtime application data.
Syntax
{
"compilerOptions": {
"incremental": true
}
}Parameters
| Name | Type | Description |
|---|---|---|
incremental | boolean | Enables persistent project-graph information for reuse by subsequent compilations. |
Key points
- incremental persists project-graph state between compiler runs.
- The default cache is represented by .tsbuildinfo files beside emitted compilation output.
- Subsequent incremental runs choose a cheaper path for checking and emitting project changes.
- A missing build-information file is generated during compilation.
Common mistakes
- The generated .tsbuildinfo files are disposable build cache files: deleting them does not affect runtime behavior, but the next compilation may need to do more work.
- Use tsBuildInfoFile when the default cache location or filename does not fit the repository’s build layout.
Example: Enable incremental compilation
{
"compilerOptions": {
"incremental": true,
"outDir": "./lib"
},
"include": ["./src"]
}Enable incremental compilation and place emitted files in lib; TypeScript stores build information there by default.
When to use it
Reuse compiler state across builds
Continuous integration
Reduce work in multi-project compilation
Monorepos
Interview questions
QWhat problem does incremental solve?
The incremental option makes TypeScript write project-graph information to disk so a later compilation can reuse it. This reduces the work needed for subsequent type-checking and emitting.
Follow-up: What happens if the cache is removed? The next build can recreate the .tsbuildinfo data and continue; the cache is not required by the emitted JavaScript.
QWhere does TypeScript store incremental build information?
By default, TypeScript creates .tsbuildinfo files in the same folder as the compilation output. Their location can be changed with tsBuildInfoFile.
Follow-up: Why might a team customize the location? A shared or dedicated build-cache directory can keep generated metadata separate from emitted artifacts.
QHow do you enable incremental compilation and customize its cache?
The option is a boolean TSConfig setting: set incremental to true to enable it. A later invocation can then use the saved project-graph information.
Follow-up: How can a project choose a custom cache path? Set tsBuildInfoFile alongside incremental in compilerOptions.
Related
tsBuildInfoFiletsc --buildproject references.tsbuildinfo