TypeScript Project References & Monorepos

Type Inference & Literal Types (const vs. let)

Discover how TypeScript infers types automatically and how let versus const declarations shape wide types versus narrow literal types.

1. Scaling Large Codebases

In large enterprise codebases and monorepos, compiling all source files as a single monolithic program slows down build times. Project References allow you to structure TypeScript code into independent, interlinked modules.

2. Enabling Composite Builds

To allow a project to be referenced by another tsconfig.json, enable "composite": true in the child project's configuration:

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

3. Referencing Sub-Projects

Reference child projects in the root or consuming app tsconfig.json:

// apps/web/tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022"
  },
  "references": [
    { "path": "../../packages/core" }
  ]
}

4. Building with Build Mode (tsc -b)

Use TypeScript's build mode (tsc -b) to compile referenced projects incrementally:

# Build referenced projects incrementally in correct dependency order!
tsc -b apps/web

5. Architectural Monorepo Benefits

• Faster Incremental Builds: TypeScript skips re-compiling referenced projects whose .d.ts outputs have not changed.
• Enforced Architectural Boundaries: Prevents illegal circular imports between separate packages in a monorepo.

6. Common Mistakes

• Forgetting declaration: true in Composite Projects: Composite project references require declaration: true to generate build declaration maps for consumer projects.

7. Congratulations!

Congratulations! You have completed all 30 foundational TypeScript Learning Bytes, mastering everything from primitive type annotations to generics, conditional types, custom utility types, and enterprise monorepo compilation!