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

Project References Basics

Using the references array to declare dependencies between TypeScript projects in a monorepo or multi-project setup.

Project References Basics

What you'll learn: How to use the references array in your tsconfig.json to declare dependencies between TypeScript projects, enabling structured multi-project builds.

The Problem: Monoliths vs Multiple Projects

When your codebase grows, you often split it into separate projects—perhaps a shared utilities library, a server package, and a client application. Without project references, TypeScript treats each project independently, forcing you to compile them in the right order manually and losing valuable type information between projects.

The references Array Solution

Project references let you declare which projects depend on others using the references array in tsconfig.json:

{
  "compilerOptions": {
    "composite": true,
    "outDir": "./dist"
  },
  "references": [
    { "path": "../shared-utils" },
    { "path": "../server-types" }
  ]
}

Each entry in the references array points to another TypeScript project (a directory containing a tsconfig.json with composite: true enabled). This tells TypeScript: "This project depends on those other projects."

How It Works

Think of project references like a dependency graph in a monorepo. When you reference another project:

  • TypeScript knows to compile that project first
  • It uses the compiled .d.ts files from referenced projects for type-checking
  • Changes in referenced projects can trigger rebuilds intelligently
  • The --build mode orchestrates everything automatically

Real-World Structure

/monorepo
  /packages
    /utils
      tsconfig.json (composite: true)
    /backend
      tsconfig.json (references utils)
    /frontend
      tsconfig.json (references utils)

The backend and frontend both depend on utilities, so their references arrays point to ../utils. TypeScript ensures utilities builds first.

Key Takeaway: Project references enable TypeScript to understand and manage dependencies between separate projects in a monorepo or multi-project setup, providing ordered builds and proper type information sharing.