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

Watch Mode with Project References

Using tsc --build --watch to automatically rebuild dependent projects when upstream changes are detected.

Watch Mode with Project References

What You'll Learn

You'll learn how to use tsc --build --watch to automatically rebuild dependent projects whenever upstream code changes, enabling fast, incremental development in multi-project TypeScript setups.

The Problem with Manual Rebuilding

When working with project references, you've learned that you can use --build mode to compile multiple interconnected projects efficiently. But during development, you don't want to manually run tsc --build every time you change a file. That's where watch mode comes in.

Combining --build and --watch

TypeScript allows you to combine the --build flag with the --watch flag:

tsc --build --watch

When you run this command, TypeScript:

  1. Performs an initial build of your project and all its references
  2. Watches all source files across the entire project graph
  3. Automatically rebuilds only the affected projects when changes are detected
  4. Respects dependencies, rebuilding downstream projects when upstream ones change

How It Works

Think of it like a smart domino system. When you change a file in Project A, watch mode:

  • Detects the change immediately
  • Rebuilds Project A incrementally (using .tsbuildinfo)
  • Automatically rebuilds Project B if it references Project A
  • Rebuilds Project C if it depends on B
  • Skips any projects that aren't affected by the change

This "cascading rebuild" happens automatically, saving you from running build commands manually or setting up complex build scripts.

Development Workflow Benefits

Watch mode with project references is particularly powerful in monorepos where you might have a common library, a server project, and a client project. Change one file in common, and both server and client automatically rebuild. You get immediate feedback without the overhead of rebuilding everything from scratch.

Key Takeaway: Use tsc --build --watch to automatically rebuild your project graph as you code, enabling fast, dependency-aware incremental compilation across multiple TypeScript projects.