TypeScript Academy · Lesson

TypeScript Project References Explained

Use composite and references settings for multi-package builds.

TypeScript Project References Explained is a free TypeScript Academy lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the TypeScript Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

What Are Project References?

Project references let you split a TypeScript codebase into multiple tsconfig projects that declare dependencies on each other, enabling incremental, isolated builds.

// tsconfig.json (root)
{
  "references": [
    { "path": "./packages/core" },
    { "path": "./packages/ui" }
  ]
}

Composite Projects

Each referenced project must have "composite": true in its tsconfig. This enables declaration caching and dependency tracking.

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

Building with tsc --build

Run tsc --build (or tsc -b) from the root to build all referenced projects in dependency order.

# Build all projects
tsc --build

# Build and watch
tsc --build --watch

# Clean build outputs
tsc --build --clean

Incremental Rebuilds

After the first build, tsc --build only recompiles projects whose source files or dependencies have changed, dramatically speeding up large repos.

# Only changed packages are rebuilt
tsc --build
# Output: 2/5 projects up to date — skipping

Declaration File Consumption

A referenced project consumes its dependencies via their generated .d.ts files in dist/, not by re-parsing the source TypeScript files.

// packages/ui imports from packages/core
import { Button } from "@myapp/core"; // resolved via dist/index.d.ts

Path Configuration

Set up paths in the root tsconfig or use exports in package.json so TypeScript resolves package imports correctly during development.

{
  "compilerOptions": {
    "paths": {
      "@myapp/core": ["./packages/core/src/index.ts"]
    }
  }
}

Preserving Build Order

TypeScript automatically determines build order from the reference graph. Circular references are detected and reported as errors.

// Circular reference error example:
// packages/core references packages/ui
// packages/ui references packages/core
// Error: Circular project reference

outDir and rootDir

Each composite project should have outDir and rootDir configured to control output layout and prevent leaking files across package boundaries.

{
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./dist"
  }
}

Integrating with Build Tools

Turborepo, Nx, and Lerna integrate with project references to cache and parallelize builds based on the dependency graph.

// turbo.json — declare TypeScript build as a pipeline step
{
  "pipeline": {
    "build": { "dependsOn": ["^build"], "outputs": ["dist/**"] }
  }
}

Watching Multiple Projects

tsc --build --watch watches all referenced projects and incrementally recompiles on every change, giving near-instant feedback in monorepos.

# Terminal: tsc --build --watch
# [9:00:01 AM] Found 0 errors. Watching for file changes.

Recap: Project References

Project references split TypeScript into isolated, cacheable build units. Set composite: true, declare references, and use tsc --build for fast, correct incremental builds in monorepos.

Quick Check

What tsconfig option is required for a project to be referenced by another?

What You Learned

TypeScript project references enable fast, isolated builds in monorepos. Configure composite: true, declare dependencies via references, and build with tsc --build for incremental compilation.

Frequently asked questions

Is the “TypeScript Project References Explained” lesson free?

Yes — the full text of “TypeScript Project References Explained” is free to read here on the web, and the TypeScript Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the TypeScript Academy course, upgrade to CoddyKit PRO.

What will I learn in “TypeScript Project References Explained”?

Use composite and references settings for multi-package builds. You practise TypeScript Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start TypeScript Academy?

No prior experience is required. TypeScript Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “TypeScript Project References Explained” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this TypeScript Academy lesson?

Yes. Every TypeScript Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

TypeScript Project References Explained
pnpm Workspaces with TypeScript
Shared Types Package Strategy
Incremental Builds and Cache in Monorepos

← Back to TypeScript Academy