Composite Projects
In this page:
{
"compilerOptions": {
"composite": true,
"declaration": true
}
}Enabling composite
Set composite to true in a project's compilerOptions when that project is meant to be referenced by another project — it's the flag that unlocks project-reference behavior for that specific tsconfig.json.
Example: Enabling composite
// tsconfig.json
// { "compilerOptions": { "composite": true } }
console.log("composite: true unlocks project-reference behavior for this config");Composite and Declaration Files
Composite projects generally need declaration output turned on so dependent projects can see and type-check against their public types without needing access to the original source files.
Example: Composite and Declaration Files
// tsconfig.json
// { "compilerOptions": { "composite": true, "declaration": true } }
console.log("Composite projects need declaration output for dependents to use");Composite and rootDir
A composite project has stricter source-file requirements than a normal project, so defining a clear rootDir keeps its output structure predictable for whatever project ends up referencing it.
Example: Composite and rootDir
// tsconfig.json
// { "compilerOptions": { "composite": true, "rootDir": "src" } }
console.log("A clear rootDir keeps composite project output structure predictable");Composite with References
Composite projects are the building blocks of a project-reference graph — each one is a self-contained unit that other projects can point at via the references array in their own tsconfig.json.
Example: Composite with References
// consumer/tsconfig.json
// { "references": [{ "path": "../composite-lib" }] }
console.log("Composite projects are the buildable units other projects reference");Incremental Builds
Composite projects work naturally with TypeScript's incremental build information, letting tsc -b skip rebuilding projects whose source hasn't changed since the previous build, which speeds up large monorepos significantly.
Example: Incremental Builds
// tsc -b (skips projects whose source hasn't changed)
console.log("Composite projects enable fast incremental builds in monorepos");- Turning on
compositewithoutdeclaration, or leaving out files frominclude, which causes errors about files not being listed. - Setting
rootDirincorrectly so files outside it cause a compile error. - Expecting
compositeto be useful in a standalone project with no references.
Chapter Quiz — Complete all 7 topics to unlock
0/7 topics done
Complete these topics first: