Project References and Incremental Builds

When Single tsconfig Isn't Enough

Here's a problem you'll definitely hit as your codebase grows: a single tsconfig.json compiling everything becomes a bottleneck. A 200-file project compiles in seconds. A 2000-file monorepo? Minutes. Project references split the codebase into independently compilable units, enabling incremental builds that only recompile what changed.

Enabling Incremental Builds

Good news: the simplest optimization doesn't even require project references:

{
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo"
  }
}

This creates a .tsbuildinfo file that caches the previous compilation. On the next compile, TypeScript diffs against the cache and only rechecks changed files and their dependents. For single-project setups, this alone can cut build times significantly.

Composite Projects

A composite project is a TypeScript project that declares itself as a buildable unit:

// packages/shared/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "declarationMap": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

composite: true enables three things:

1. Forces declaration: true (generates .d.ts files)
2. Forces rootDir to be set
3. Enables the project to be referenced by other projects

Project References

The root tsconfig.json references composite sub-projects:

// tsconfig.json (root)
{
  "references": [
    { "path": "packages/shared" },
    { "path": "packages/server" },
    { "path": "packages/client" }
  ],
  "files": [] // Root doesn't compile anything itself
}

Each sub-project can reference other sub-projects:

// packages/server/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "references": [
    { "path": "../shared" }
  ],
  "include": ["src"]
}

Build Mode

This is important — you need to use tsc --build (or tsc -b) to compile project references, not plain tsc:

# Build all projects in dependency order
tsc --build

# Build a specific project and its dependencies
tsc --build packages/server

# Force rebuild everything
tsc --build --force

# Clean build outputs
tsc --build --clean

# Watch mode with project references
tsc --build --watch

# Verbose output (shows what's being rebuilt)
tsc --build --verbose

Monorepo Setup

A typical monorepo with project references:

monorepo/
├── tsconfig.json              # Root — references all packages
├── packages/
│   ├── shared/
│   │   ├── tsconfig.json      # composite: true
│   │   ├── src/
│   │   │   ├── types.ts
│   │   │   └── utils.ts
│   │   └── dist/              # Build output + .d.ts files
│   ├── api/
│   │   ├── tsconfig.json      # references: [shared]
│   │   └── src/
│   └── web/
│       ├── tsconfig.json      # references: [shared]
│       └── src/

// packages/shared/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler"
  },
  "include": ["src"]
}

// packages/web/tsconfig.json
{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "jsx": "react-jsx",
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler"
  },
  "references": [
    { "path": "../shared" }
  ],
  "include": ["src"]
}

// WRONG — relative import crossing project boundary
import { User } from "../../shared/src/types";

// CORRECT — import from the package
import { User } from "@myorg/shared";

Production Scenario: Full Monorepo Configuration

// Root tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true
  }
}

// packages/shared/tsconfig.json
{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "declarationMap": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

// packages/shared/package.json
{
  "name": "@myorg/shared",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    }
  },
  "files": ["dist"]
}

Challenge: Configure a 3-Package Monorepo

// Set up TypeScript project references for this monorepo structure:
//
// packages/
//   types/       — shared TypeScript types (no runtime code)
//   core/        — business logic (depends on types)
//   web/         — React app (depends on types AND core)
//
// Requirements:
// 1. All packages use strict mode
// 2. types/ generates .d.ts files only (declarationOnly)
// 3. core/ depends on types/
// 4. web/ depends on both types/ and core/
// 5. Root tsconfig.json references all three
//
// Write all four tsconfig.json files:

// tsconfig.json (root)
{
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "references": [
    { "path": "packages/types" },
    { "path": "packages/core" },
    { "path": "packages/web" }
  ],
  "files": []
}

// packages/types/tsconfig.json
{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "emitDeclarationOnly": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

// packages/core/tsconfig.json
{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "references": [
    { "path": "../types" }
  ],
  "include": ["src"]
}

// packages/web/tsconfig.json
{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "outDir": "dist",
    "rootDir": "src",
    "jsx": "react-jsx"
  },
  "references": [
    { "path": "../types" },
    { "path": "../core" }
  ],
  "include": ["src"]
}

The key: each package uses extends for shared options, composite: true for independent compilation, and references for type-safe cross-package imports. Run tsc --build from the root to compile all packages in the correct dependency order.