Project references

Why split builds

One giant project rebuilds everything on every change. Splitting shared code, server code, and client code into linked projects lets the compiler rebuild only what changed.

Small projects also give clearer errors. A failure names the project first, so you open the right folder instead of hunting through the whole tree.

{ "compilerOptions": { "composite": true, "strict": true } }

references in tsconfig

A reference declares that one project depends on another. The app project points at the shared project, and the compiler builds shared first automatically.

References also carry types across the boundary. Imports from the shared project check against its declarations without copying files around.

{ "references": [ { "path": "shared" }, { "path": "server" } ] }

tsc --build

Build mode understands references and skips work that is already fresh. Run one command at the root and every project builds in dependency order.

Later runs are incremental. Unchanged projects are skipped in seconds while edited ones rebuild with all dependents.

tsc --build

projects build in dependency order

When references win

References shine once a codebase has a shared core plus two or more apps or services. Below that size a single project stays simpler and faster to explain.

Reach for them when full builds feel slow or when teams step on shared files. Split at the natural seam and keep each project focused on one job.

import { formatPrice } from "shared"; const label = formatPrice(1999); console.log(label);

Next: Publishing packages

Article author: Arthur Isaev