Project references: tsc --build, composite, and the incremental build graph

The shape: a project that points at its dependencies

Each package has its own tsconfig.json. A package that depends on another lists it under references, and the referenced project must be composite:

// packages/web/tsconfig.json
{
  "compilerOptions": { "composite": true, "outDir": "dist" },
  "references": [
    { "path": "../core" },   // web depends on core
    { "path": "../ui" }      // and on ui
  ]
}

// packages/core/tsconfig.json
{
  "compilerOptions": {
    "composite": true,        // REQUIRED to be referenced
    "declaration": true,      // composite implies this; types are the cross-project contract
    "outDir": "dist"
  }
}

composite: true flips on three things: it forces declaration: true (so the project emits .d.ts — the interface other projects consume instead of source), it forces incremental behaviour with a .tsbuildinfo, and it requires that every input file is covered by include/files (so the build can hash inputs reliably).

tsc --build walks the reference graph

A normal tsc build of a project with references would fail or ignore them. You must use build mode: tsc --build (or tsc -b). Build mode reads the reference graph, topologically sorts it, and builds dependencies before dependents — and skips any project whose inputs are unchanged since its .tsbuildinfo:

tsc --build packages/web   # builds core, then ui, then web — in dependency order
tsc --build --verbose      # prints which projects are up-to-date vs rebuilt
tsc --build --clean        # deletes all outputs + .tsbuildinfo (the stale-cache cure)
tsc --build --force        # ignores .tsbuildinfo, rebuilds everything

Incrementality and .tsbuildinfo

Before you accept a 90-second type-check on every save, ask yourself: does your tsconfig know which files belong to each package? If not, tsc re-hashes everything every time.

.tsbuildinfo is a cache of file hashes and signatures. On rebuild, tsc -b compares current inputs to the cached state; if a project’s inputs (and the .d.ts of its dependencies) are unchanged, it’s up to date and skipped entirely. Crucially, a project only needs to rebuild a dependent when its public .d.ts actually changed — an internal-only edit that doesn’t alter the emitted types lets dependents stay cached (the “signature” optimisation).

This is also why editors feel snappier: each referenced project is type-checked in isolation, so the language server doesn’t re-analyse the whole monorepo on every keystroke.

The traps

error TS6306: Referenced project must have setting "composite": true — you referenced a project that isn’t composite. Add composite: true to the referenced one (a common confusion: people add it to the referrer).

Stale .tsbuildinfo — if you change something the cache doesn’t track (a compiler upgrade with a quirk, a hand-edited dist), the build may wrongly think a project is up to date. Cure: tsc -b --clean then rebuild, or --force.

Circular references — A references B and B references A is rejected (TS6202); a build DAG must be acyclic. Break the cycle by extracting the shared types into a third leaf project both depend on.

Path mapping across projects — paths aliases still aren’t rewritten on emit (lesson 02), so cross-project imports should go through the package’s real entry/exports, not a paths alias that only the type-checker understands.

Together, these four traps share a pattern: the error points at the referenced project, not the referrer; the cache is a file you can always delete; cycles require a new leaf to break; and aliases are a type-checker fiction that must not leak into emit.