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:
- Performs an initial build of your project and all its references
- Watches all source files across the entire project graph
- Automatically rebuilds only the affected projects when changes are detected
- 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.