Project references
A monorepo splits packages into independently compiled TypeScript projects connected by references.
TypeScript · Const
composite
composite makes a TypeScript project suitable for project references and build-mode analysis by enforcing a complete, known input set. It also changes the default rootDir and enables declaration output by default.
How it works
Setting composite enables constraints that let TypeScript and build tools determine efficiently whether a project has already been built. It changes the default rootDir, requires every implementation file to be covered by include or files, and makes declaration output enabled by default.
Syntax
{
"compilerOptions": {
"composite": true
}
}Parameters
| Name | Type | Description |
|---|---|---|
composite | boolean | Enables constraints required for efficient project-reference and build-mode checks. |
Returns
A TSConfig compiler option; when enabled, it changes project constraints and defaults for build and declaration analysis.
Key points
- It adds project constraints that help TypeScript and other build tools determine whether the project has already been built.
- The option is particularly relevant when TypeScript itself is running in build mode.
- With
compositeenabled, declaration generation is on by default. - Projects consumed through project references need this option enabled.
Common mistakes
- Every implementation file must be included explicitly through an
includepattern or thefilesarray; otherwisetscreports the unspecified files. - Turning on
compositecan change the inferredrootDir, so projects relying on the previous inferred location should set it explicitly. - A project used as a reference must enable
composite; configuring references alone is insufficient.
Example: Composite project configuration
{
"compilerOptions": {
"composite": true,
"outDir": "dist"
},
"include": ["src/**/*.ts"]
}This configuration makes the project suitable for build-mode project references while explicitly including every implementation file.
When to use it
Incremental build orchestration
A large codebase uses tsc --build to determine which projects need rebuilding.
Typed package boundaries
A library project needs declaration files for consumers and wants declaration generation enabled by default.
Interview questions
QWhy would you enable composite?
composite imposes project constraints that allow TypeScript and build tools in --build mode to determine quickly whether a project has been built. It is primarily used for projects participating in project references.
Follow-up: What happens to declaration output when composite is enabled? declaration defaults to true, so the project produces declaration files unless configured otherwise.
QHow does composite affect rootDir?
If rootDir is omitted, TypeScript uses the directory containing the project’s tsconfig.json as the default. This differs from the usual inferred root based on the common path of input files.
Follow-up: How can you avoid an unintended output layout? Set rootDir explicitly to the directory whose structure should be preserved in the output.
QWhat file-listing rule does composite enforce?
Every implementation file must be known through an include pattern or the files list. If a file is outside those declarations, tsc reports which files were not specified.
Follow-up: Why does this help build mode? Knowing the complete input set lets TypeScript determine project state and dependencies without discovering files unpredictably.
Related
referencesdeclarationrootDirincludefilestsc --build