TypeScript Reference ยท tsconfig: Projects, Files and Watch Options
TypeScript composite option
Reference for the TypeScript composite compiler option: what it enforces, which defaults it changes, and why referenced projects must turn it on.
"composite": true marks a tsconfig project as a building block that other projects can depend on. It does not change how your code is type-checked. Instead it adds a set of rules that make the project's output predictable, so that tsc --build can decide quickly whether the project is up to date and other projects can read its declaration files instead of re-checking its sources.
You need it whenever a project is listed in another project's references. Typical uses are a monorepo with core, server and client packages, or a repository that keeps production code and tests in separate projects.
{ "compilerOptions": { "composite": true, "outDir": "dist", "rootDir": "src" }, "include": ["src"] }
Try it
The compiler needs several tsconfig files to show composite at work, so this site cannot run it directly. These examples model the rules in ordinary TypeScript so you can see what is checked.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Syntax
{ "compilerOptions": { "composite": true } }
tsc --composite tsc --build
| Value | Description |
|---|---|
true |
Apply the rules below. |
false (default) |
Ordinary project; it cannot be referenced by others. |
What composite enforces:
declarationdefaults totrue, andincrementaldefaults totrue.rootDirdefaults to the folder holding the tsconfig file when it is not set.- Every implementation file must be matched by
includeor listed infiles; otherwise the compiler reports error TS6307. - The output
.d.tsfiles and the.tsbuildinfofile are written next to the JavaScript output, sooutDirshould be set.
Usage notes
- A referenced project must be composite. Referencing one that is not produces an error (TS6306).
- Declaration maps help editors. Add
"declarationMap": trueso that "Go to definition" lands in the source and not in a.d.tsfile. - It is about builds, not types. Turning
compositeon never makes valid code invalid, apart from the include rule above. - Use it with
tsc --build. Plaintsc -pcompiles one project and does not build its references first. - Keep
rootDirexplicit when sources live in a subfolder; otherwise the output layout can change when you add a file outside it. - A solution file (a tsconfig with
"files": []and onlyreferences) is a common root that builds every project.