Skip to content
Tutorials Center
My learning

Topics

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.

JSON
{
  "compilerOptions": { "composite": true, "outDir": "dist", "rootDir": "src" },
  "references": [{ "path": "../contracts" }],
  "include": ["src"]
}

Try it

TypeScript A shared contract keeps two sides consistent

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.

TypeScript How a workspace name finds its folder

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

TEXT
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, module and friends in tsconfig.base.json and use extends in each package.
  • composite. Required for referenced projects. It turns on declaration, requires every file to be matched by include or files, and writes .tsbuildinfo.
  • references. Declares which projects this one imports. Imports of a referenced project resolve to its generated .d.ts files 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 types and exports pointing at built .d.ts files, 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.ts files at least once.
  • Never import another package's src by relative path (../../other/src/x). It breaks rootDir and 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 types at source and letting a bundler compile; trade-offs are slower editor checks and weaker boundaries.
  • CI: run tsc --build at the root once, then tests per package.