Project references and monorepos
Split a large TypeScript repo into composite projects linked with references, build them with tsc --build, and know when workspace packages suffice.
Project references and monorepos
The player loads from youtube-nocookie.com when you press play. Nothing reaches YouTube before that.
Not started
What you'll learn
- In one big tsconfig, every check rebuilds the whole program, so a one-line change still pays for every file in the repo. Project references split the repo into smaller projects the compiler can build, cache, and skip independently.
- A referenced project must set `composite: true`, which turns on declaration output and incremental build info and requires every source file to be matched by `include` or `files`.
- `references` in a consuming tsconfig points at another project's folder. Imports from that project are then type-checked against its emitted `.d.ts` files rather than re-checking its source.
- `tsc --build` (or `tsc -b`) walks the reference graph in dependency order, rebuilds only projects whose inputs changed, and records what it did in `.tsbuildinfo` files.
- Workspace packages, where each package is imported by name through npm, pnpm, or Yarn workspaces, are the common alternative. They can be combined with references or used alone when the repo is small enough that one type check stays fast.
One giant program
A single tsconfig.json describes one program. When you run tsc, it parses and checks every file that program includes. In a repo with a shared library, an API server, a web app, and a set of scripts, that means fixing a typo in a script re-checks the web app, the server, and the library too. The editor carries the same load: it holds the entire program in memory to answer a hover.
At a few hundred files nobody notices. At several thousand, type checks take minutes and the editor lags. You also lose a useful boundary: nothing stops the web app from importing a private file deep inside the server.
Project references cut the repo into separate programs with declared dependencies between them. Think of it as the difference between rebuilding a whole building after every repair and treating each floor as its own unit with a known interface to the others.
A composite project
Every project that others depend on sets composite: true:
// packages/shared/tsconfig.json
{
"compilerOptions": {
"composite": true,
"target": "es2022",
"module": "nodenext",
"strict": true,
"rootDir": "src",
"outDir": "dist"
},
"include": ["src"]
}
composite switches on several things together:
- Declaration output.
declarationis turned on, so buildingsharedproducesdist/money.d.tsnext todist/money.js. Those.d.tsfiles are the floor’s interface. Other projects check against them. - Incremental build info. The compiler writes a
tsconfig.tsbuildinfofile recording the inputs, outputs, and hashes from the last build, so it can tell whether anything changed. - A closed file list. Every source file must be matched by
includeorfiles. A project whose inputs are fuzzy can’t be safely skipped.
Referencing it
The consumer lists the projects it depends on:
// packages/api/tsconfig.json
{
"compilerOptions": {
"composite": true,
"target": "es2022",
"module": "nodenext",
"strict": true,
"rootDir": "src",
"outDir": "dist"
},
"include": ["src"],
"references": [{ "path": "../shared" }]
}
Now import { formatCents } from "../../shared/src/money.js" inside api resolves to shared’s built money.d.ts. The compiler doesn’t re-check shared’s source. Without the reference, the same import fails with “File is not under rootDir”, because api would be trying to swallow another project’s source into its own program.
Finally, a root “solution” config ties the projects together:
// tsconfig.json
{
"files": [],
"references": [
{ "path": "packages/shared" },
{ "path": "packages/api" }
]
}
"files": [] means the root compiles nothing itself. It only exists to name the graph.
Building with tsc --build
Plain tsc -p builds one project. tsc --build, or tsc -b, builds a graph:
tsc -b # build everything the root references, in dependency order
tsc -b --verbose # print why each project was built or skipped
tsc -b --watch # rebuild affected projects on change
tsc -b --clean # delete outputs
On the first run it builds shared, then api. Change only a file in api and run it again: the verbose output reports shared as up to date and rebuilds just api. In a large repo this is where the time savings come from. Unchanged projects cost a timestamp check, and changed ones are checked against small .d.ts interfaces rather than the source of everything they import. In CI, caching the dist and .tsbuildinfo files between runs carries the same benefit across machines.
Editors understand references too. When you jump to a definition in shared from api, the editor opens the real source, not the .d.ts, and only loads the projects you actually work in.
The rules for how that relative import, or a package name, gets resolved are the subject of module resolution.
Workspace packages instead
The other common monorepo shape skips references. With npm, pnpm, or Yarn workspaces, shared becomes a package named @acme/shared, and api imports it by name. If @acme/shared’s package.json points its exports straight at TypeScript source, sometimes called an internal package, the consumer’s tsconfig or bundler compiles it as part of its own program. That’s simple to set up and works well while the repo is small, but it brings back the one-giant-program cost. Many large repos use both: workspaces for naming and dependency management, references for incremental type checks. Task runners like Nx and Turborepo add caching on top of either.
What the video covers
The Nx video contrasts paths aliases with project references. Aliases make cross-package imports look tidy, but on their own they still put every file into one program. It then sets up project references with composite and tsc -b, and shows the incremental type-checking and CI speed-ups that follow. It ends with a short mention of Nx, though the technique is plain TypeScript and needs no extra tooling. Ahmed Elsakaan’s video in the links compares internal packages with references in a demo repo, if you want to see that trade-off in more detail.
Check yourself
Why does a referenced project need `composite: true`?
The consumer reads the referenced project's declaration output instead of its source, and `tsc -b` needs to know cheaply whether that output is current. `composite` guarantees both: it forces declaration emit, enables the incremental `.tsbuildinfo` record, and requires every source file to be listed so the build knows exactly what the inputs are.
Where do a project's types come from when another project imports it through a reference?
From the `.d.ts` files the referenced project emitted to its `outDir`. The consumer never re-checks the referenced project's source, which is a large part of why references are faster.
You change one file in `packages/api` and run `tsc -b`. Why doesn't `packages/shared` get rebuilt?
`tsc -b` compares each project's inputs with the state saved in its `.tsbuildinfo` file. `shared` has no changed inputs, so it is skipped. Only `api` and any projects that reference `api` are checked again.
What is the root tsconfig with `"files": []` and a list of references for?
It is a solution file: a single entry point that names every project, so `tsc -b` at the root builds the whole graph. The empty `files` stops the root from compiling anything itself.
Go deeper
Notes
Notes are saved to your account.
Everything else on this page works without one — progress and bookmarks keep themselves in this browser and come with you when you sign in. Notes are the one thing worth not trusting to a browser you might clear.
Your notes could not be loaded.