TypeScript Reference ยท Concepts and Comparisons
Monorepos and TypeScript project references
How to structure a TypeScript monorepo: workspaces, a shared base tsconfig, composite projects, references, tsc --build and sharing types between packages.
A monorepo keeps several packages in one repository so they can share code and change together. In TypeScript this raises two questions: how does package A import package B's types, and how do you avoid re-checking the whole repository after a one-line change?
The answers are workspaces and project references. Workspaces (npm, pnpm or Yarn) link local packages into node_modules so import "@acme/contracts" resolves to the folder in your repository. Project references split the compilation into several tsconfig.json projects that depend on each other and are built in order, each with its own cached output.
{ "compilerOptions": { "composite": true, "outDir": "dist", "rootDir": "src" }, "references": [{ "path": "../contracts" }], "include": ["src"] }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Layout
repo/ package.json workspaces: ["apps/*", "packages/*"] tsconfig.base.json shared compiler options tsconfig.json solution file: references only, "files": [] packages/contracts/ tsconfig.json with composite: true packages/utils/ references contracts apps/api/ references contracts and utils apps/web/ references contracts
The root tsconfig.json is a "solution" file. It lists every project in references, sets "files": [] so it compiles nothing itself, and lets tsc --build build everything in dependency order.
Pieces you need
- Base options. Put
strict,target,moduleand friends intsconfig.base.jsonand useextendsin each package. - composite. Required for referenced projects. It turns on
declaration, requires every file to be matched byincludeorfiles, and writes.tsbuildinfo. - references. Declares which projects this one imports. Imports of a referenced project resolve to its generated
.d.tsfiles instead of its source, so its source is not rechecked. - tsc --build. Builds projects in order and skips those whose inputs have not changed.
- Package entry points. Give each package
typesandexportspointing at built.d.tsfiles, or at source during development, consistently across the repo. See package.json exports. - Path aliases are not a substitute. paths only teaches the compiler a mapping; the bundler or runtime needs the same mapping, which workspaces provide for free.
Usage notes
- Build before checking dependants. Editors show errors until the referenced project has produced its
.d.tsfiles at least once. - Never import another package's
srcby relative path (../../other/src/x). It breaksrootDirand the project boundary. - Keep the graph acyclic. References cannot form cycles; extract the shared part into a third package.
- Declaration emit must be possible. Exported values whose types cannot be named produce errors such as TS2742; add explicit annotations.
- Faster alternatives exist. Some setups skip the build step by pointing
typesat source and letting a bundler compile; trade-offs are slower editor checks and weaker boundaries. - CI: run
tsc --buildat the root once, then tests per package.