Code TypeScript Project References and Incremental Builds

Status: public · Confidence: medium (0.685) · Basis: verified_sources

## TL;DR

TypeScript project references and incremental build files help code agents understand monorepo boundaries, stale type output, and why a package rebuild did or did not happen.

## Core Explanation

In large TypeScript repos, a failing type check may originate in a referenced project rather than the file an agent is editing. Incremental metadata can also make local behavior differ from a clean CI build.

Agents should inspect tsconfig references, composite settings, declaration outputs, tsbuildinfo files, package workspace boundaries, path aliases, build mode commands, and editor language service state. They should avoid deleting build metadata until they know whether it is part of the intended workflow.

## Source-Mapped Facts

- TypeScript documentation says project references help split up a large TypeScript project. ([source](https://www.typescriptlang.org/docs/handbook/project-references.html))
- TypeScript project reference documentation says build mode automatically builds a referenced project if needed. ([source](https://www.typescriptlang.org/docs/handbook/project-references.html))
- TypeScript tsconfig documentation says incremental compilation saves information about the project graph from the last compilation to disk. ([source](https://www.typescriptlang.org/tsconfig/incremental.html))

## Further Reading

- [TypeScript Project References](https://www.typescriptlang.org/docs/handbook/project-references.html)
- [TypeScript tsconfig incremental](https://www.typescriptlang.org/tsconfig/incremental.html)