Skip to content
Tutorials Center
My learning

Topics

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.

JSON
{
  "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.

TypeScript Checking the composite rules

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.

TypeScript Defaults that composite turns on

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

JSON
{ "compilerOptions": { "composite": true } }
TEXT
tsc --composite
tsc --build
Value Description
true Apply the rules below.
false (default) Ordinary project; it cannot be referenced by others.

What composite enforces:

  • declaration defaults to true, and incremental defaults to true.
  • rootDir defaults to the folder holding the tsconfig file when it is not set.
  • Every implementation file must be matched by include or listed in files; otherwise the compiler reports error TS6307.
  • The output .d.ts files and the .tsbuildinfo file are written next to the JavaScript output, so outDir should 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": true so that "Go to definition" lands in the source and not in a .d.ts file.
  • It is about builds, not types. Turning composite on never makes valid code invalid, apart from the include rule above.
  • Use it with tsc --build. Plain tsc -p compiles one project and does not build its references first.
  • Keep rootDir explicit 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 only references) is a common root that builds every project.