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

Building with --build Mode

How tsc --build orchestrates incremental compilation across referenced projects and manages build order automatically.

Building with --build Mode

What you'll learn: How tsc --build orchestrates incremental compilation across referenced projects and manages build order automatically.

The Problem with Plain tsc

When you have multiple TypeScript projects linked via project references, running tsc in each directory manually becomes tedious and error-prone. You need to build projects in the correct dependency order, track which ones need rebuilding, and remember which commands to run where.

How --build Mode Works

The --build flag (shorthand: -b) transforms the TypeScript compiler into an intelligent build orchestrator:

tsc --build

When you run this command, TypeScript:

  1. Reads your project references from tsconfig.json
  2. Determines the dependency graph — which projects depend on which
  3. Calculates the correct build order automatically
  4. Builds only what's changed using incremental compilation
  5. Skips up-to-date projects entirely

Think of It Like a Chef

Imagine a restaurant kitchen where dishes have dependencies. The salad needs chopped vegetables, the main course needs the salad as a side, and dessert is independent. A good kitchen manager doesn't remake everything — they check what's fresh, what needs prep, and coordinate the right order. That's exactly what --build mode does for your TypeScript projects.

Build Order Automation

You never specify the order manually. TypeScript analyzes your "references" array in each tsconfig.json and builds upstream dependencies first, then downstream consumers. If Project B references Project A, TypeScript always compiles A before B — guaranteed.

Incremental Intelligence

Because composite: true creates .tsbuildinfo files, --build mode knows which files changed since the last compilation. It rebuilds only affected projects, making large codebases compile dramatically faster on subsequent builds.

Key Takeaway: tsc --build orchestrates multi-project compilation by automatically determining build order from project references and leveraging incremental compilation to rebuild only what's necessary, making it the go-to command for TypeScript monorepos and composite project setups.