Course contentsShow
← TypeScript
Lesson 1229 of 1,79628. tsconfig in DepthFree lesson

Monorepo Patterns with References

Organizing packages, shared libraries, and apps in a monorepo using project references for clean boundaries.

Monorepo Patterns with References

What You'll Learn

You'll learn how to structure a TypeScript monorepo with multiple packages, shared libraries, and applications using project references to maintain clean boundaries and enable efficient incremental builds.


The Monorepo Structure Problem

A monorepo is a single repository containing multiple related projects—think shared utility libraries, core business logic packages, and several applications (web, mobile, admin) that consume them. Without proper organization, TypeScript struggles: build times explode, circular dependencies creep in, and type-checking becomes unbearably slow.

Project references solve this by letting you explicitly define the relationships between projects, enabling TypeScript to build only what changed and enforce architectural boundaries.


Common Monorepo Patterns

Pattern 1: Layered Libraries

Organize your monorepo into layers, where each layer depends only on layers below:

/packages
  /utils          (no dependencies)
  /core           (depends on utils)
  /api-client     (depends on core, utils)
/apps
  /web-app        (depends on api-client, core, utils)
  /admin-app      (depends on api-client, core)

Each folder has its own tsconfig.json with composite: true, and references pointing to dependencies:

// apps/web-app/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "composite": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "references": [
    { "path": "../../packages/api-client" },
    { "path": "../../packages/core" },
    { "path": "../../packages/utils" }
  ],
  "include": ["src"]
}

Pattern 2: Domain-Driven Packages

Group by business domain rather than technical layer:

/packages
  /auth-domain
  /billing-domain
  /user-domain
  /shared-types
/apps
  /customer-portal
  /internal-dashboard

Each domain can reference shared-types but domains don't reference each other directly, keeping boundaries clear.

Pattern 3: Application-Specific Libraries

Some libraries exist only to support specific apps:

/libs
  /shared-ui       (used by all apps)
  /web-utils       (web-app only)
  /mobile-bridge   (mobile-app only)
/apps
  /web-app         (refs: shared-ui, web-utils)
  /mobile-app      (refs: shared-ui, mobile-bridge)

This prevents bloating apps with unused code while sharing common foundations.


Benefits of This Approach

  • Incremental builds: TypeScript only rebuilds changed projects and their dependents
  • Enforced boundaries: Can't accidentally import from admin-app into customer-portal
  • Clear dependency graph: references explicitly document what depends on what
  • Parallel builds: Independent projects can compile simultaneously
  • Type safety across packages: No more loose any types at package boundaries

Key Takeaway: Organizing a monorepo with project references creates explicit architectural boundaries—shared libraries provide reusable functionality, applications compose them together, and TypeScript ensures everything stays in sync with fast, incremental builds.