Scaling TypeScript: Project References, Composite Builds, and Fast CI

What you’ll learn

• Why big repos get slow and how TS project references help
• What composite really means
• A practical setup for monorepos or multi-package apps

30‑second interview answer

Project references let TypeScript treat a codebase as multiple smaller projects with explicit dependencies. Each project can be built incrementally and cached, which speeds up local builds and CI. The key pieces are references, composite: true, and emitting declarations so dependent projects can type-check against outputs.

The problem: one giant TS program

In a large repo, a single tsc -p tsconfig.json can become slow because TS re-checks everything.

Project references solve this by:

• Splitting into smaller graphs
• Caching build info per project
• Allowing incremental rebuilds

Minimal example

Root tsconfig

{
  "files": [],
  "references": [
    { "path": "./packages/ui" },
    { "path": "./packages/api" }
  ]
}

Package tsconfig (packages/ui/tsconfig.json)

{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "declarationMap": true,
    "outDir": "dist",
    "tsBuildInfoFile": "dist/.tsbuildinfo"
  },
  "include": ["src"]
}

Now TS can build the graph:

tsc -b

What composite implies

• TS will enforce certain constraints that make builds reliable
• It enables build info generation for incremental builds

Boundary rules (how you keep it healthy)

• Each package exposes a public API (index.ts)
• Dependent packages import only from public API
• Avoid circular dependencies between referenced projects

Production rule of thumb

• Use project references when you have:
  • monorepos
  • multiple packages
  • slow CI from large TS builds

If your repo is small, don’t add this complexity.

Interview questions

1. Q: What’s the benefit of project references?

   • A: Faster builds via incremental compilation and cached outputs per project.

2. Q: What is tsc -b?

   • A: Build mode that builds a graph of referenced projects in the correct order.

Quick recap

• References split your code into buildable chunks.
• composite + tsc -b enables fast incremental builds.
• Enforce boundaries to avoid dependency spaghetti.