Project References & Incremental Builds

## The problem composite solves Without project references, a large TypeScript codebase is one compilation: `tsc` loads every source file reachable from the entry points and checks the lot. Every edit re-checks everything, and nothing enforces that the payments code may not reach into the internals of the auth code. Project references split that into several independently buildable compilations that know about each other. `"composite": true` is the flag that makes one tsconfig.json eligible to be such a unit — it is the producer side of the feature, while the `references` array is the consumer side. ```json { "compilerOptions": { "composite": true, "declaration": true, "declarationMap": true, "rootDir": "./src", "outDir": "./dist" }, "include": ["src"] } ``` ## What the flag turns on **Declaration emit is mandatory.** A composite project must emit `.d.ts` files, and the compiler rejects `"declaration": false` alongside `composite`. The reason is structural: when project B references project A, B does not type-check A's sources — it consumes A's emitted declarations. Those declarations are A's public contract, and without them the reference cannot be resolved. This is also why a composite project's public API must be expressible in a `.d.ts` file; a type the compiler cannot name in output produces a declaration-emit error that a non-composite project would never have hit. **Build info is produced.** Composite projects participate in incremental building: the compiler writes a `.tsbuildinfo` file recording what it compiled and with which options, which build mode later reads to decide whether the project needs rebuilding at all. `tsBuildInfoFile` moves that file if the default location is inconvenient. **The input set must be complete and static.** `rootDir` defaults to the directory containing the tsconfig.json rather than being inferred from the common ancestor of the input files, so the output layout under `outDir` is predictable. More importantly, every implementation file the compilation ends up including must be matched by `files` or `include`. If a source file is pulled in only because something imports it, but no glob covers it, you get: ``` error TS6059: File '/repo/packages/util/src/x.ts' is not listed within the file list of project '/repo/packages/api/tsconfig.json'. Projects must list all files or use an 'include' pattern. ``` That error is almost always the real diagnosis behind "composite broke my build": a project is reaching directly into another package's sources instead of going through a reference. The fix is to add a reference and import from the package, not to widen the glob until the error stops. ## The consumer side A project declares its dependencies with `references`, each entry pointing at a directory containing a tsconfig.json or at the config file itself: ```json { "references": [{ "path": "../core" }, { "path": "../logging" }] } ``` Every referenced project must be composite; otherwise the compiler reports that the referenced project must have the `composite` setting enabled. Two useful consequences follow from the reference being explicit. Imports are now checked against a declared graph, so an unreferenced package's types are simply not visible — the module boundary is enforced by the compiler rather than by convention. And the build order is derivable: build mode topologically sorts the graph rather than asking you to script it. ## What composite does not do It does not bundle, it does not link packages, and it does not change emitted JavaScript semantics — types are still erased, and the output of a composite project is the same JavaScript you would have got otherwise, plus declarations and a build-info file. It also does not resolve package names for you: the reference tells the compiler about build ordering and about which declarations back an import, while resolving `@acme/core` to a location is still ordinary module resolution — via the workspace's node_modules layout or explicit path mapping. It is also not free. Every consumer is now type-checked against generated `.d.ts` output rather than the original source, so a stale build of an upstream project produces confusing downstream errors, and a change to an upstream public type is only visible once that project has been rebuilt. That tradeoff is the reason `declarationMap` is near-mandatory alongside `composite` in a repo people edit daily. ## Reading the flag in an interview The compact way to answer: `composite` promises the compiler that this project can be built on its own and consumed as declarations. The requirements — mandatory declaration emit, a fully enumerated input set, a defaulted `rootDir`, and a build-info file — are all consequences of that one promise.