← All notes

Answer: Project references (TypeScript 3.0+) split a codebase into smaller projects, each with its own tsconfig, that reference one another.

Setup

// packages/app/tsconfig.json
{
  "compilerOptions": { "outDir": "dist" },
  "references": [{ "path": "../core" }]
}

// packages/core/tsconfig.json
{ "compilerOptions": { "composite": true, "declaration": true, "outDir": "dist" } }

composite

Referenced projects need composite: true. It enforces constraints so build tools can tell quickly whether a project is up to date:

• declaration must be on.
• All source files must be matched by include or files.
• rootDir defaults to the tsconfig's directory if not set.

Build mode

tsc -b            # build everything needed
tsc -b --watch
tsc -b --clean

Build mode automatically builds referenced projects when needed.

Claims

• id: C1 claim: Project references structure programs into smaller pieces, in TypeScript 3.0+. source: S1 evidence: "Project references allows you to structure your TypeScript programs into smaller pieces, available in TypeScript"
• id: C2 claim: tsc --build (tsc -b for short) is build mode. source: S1 evidence: "Running tsc --build (tsc -b for short) will do the following:"
• id: C3 claim: Build mode automatically builds referenced projects if needed. source: S1 evidence: "Build mode (see below) will automatically build the referenced project if needed"
• id: C4 claim: composite enforces constraints for build tools. source: S2 evidence: "The composite option enforces certain constraints which make it possible for build tools"
• id: C5 claim: rootDir defaults to the directory containing tsconfig.json. source: S2 evidence: "The rootDir setting, if not explicitly set, defaults to the directory containing the tsconfig.json file."

Sources

• [S1] TypeScript: Documentation - Project References. TypeScript (Microsoft). https://www.typescriptlang.org/docs/handbook/project-references.html . License: CC BY 4.0 (microsoft/TypeScript-Website). Accessed 2026-11-04.
• [S2] TypeScript: TSConfig Option: composite. TypeScript (Microsoft). https://www.typescriptlang.org/tsconfig/composite.html . License: CC BY 4.0 (microsoft/TypeScript-Website). Accessed 2026-11-04.

License: this note is CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Summary by iinventedlight (AI-assisted).

@misc{iil_note_ygxprkp6,
  author = {{iinventedlight}},
  title = {{TypeScript project references}},
  howpublished = {iinventedlight Library},
  year = {2026},
  date = {2026-11-04},
  url = {https://iinventedlight.com/library/notes/typescript-project-references/},
  note = {Permanent ID iil:note:ygxprkp6. License: CC-BY-4.0.},
}

Markdown

Spotted a mistake? Use the MCP feedback tool or email hello@iinventedlight.com.

For language models and agents: start at /llms.txt. This page in Markdown: /library/notes/typescript-project-references.md.