TIL: Structuring Monorepos With TypeScript Project References

Monorepos with TypeScript compile everything by default. Project references tell TypeScript to build each package independently and only rebuild what changed.

// tsconfig.json at the root
{
  "references": [
    { "path": "packages/sdk-core" },
    { "path": "packages/sdk-rest" },
    { "path": "packages/sdk-websocket" }
  ]
}

Each referenced package has its own tsconfig.json with composite: true.

// packages/sdk-core/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "outDir": "./dist",
    "rootDir": "./src"
  }
}

tsc --build

The –build flag compiles only the packages that changed since the last build. Incremental builds drop from minutes to seconds.

Does this work with npm workspaces?

Yes. Combine project references with npm workspaces for monorepo dependency management.

Can I build a single package?

tsc --build packages/sdk-core

Target a specific project reference without building the whole tree.