Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท The tsc Command Line

tsc --build

Reference for tsc --build (-b): building referenced projects in dependency order, skipping up-to-date ones, and the clean, force and verbose options.

tsc --build (short form -b) is the "build mode" of the compiler. Given one or more projects, it reads their references, builds every referenced project first, and skips projects whose outputs are already up to date. It is what makes large multi-package repositories fast to rebuild.

Build mode requires projects to be composite (or at least declare their outputs), because a project is only built from the .d.ts files of the projects it references.

TEXT
tsc --build
tsc -b packages/app packages/server
tsc -b --verbose
tsc -b --clean

Try it

In a referenced project, each package exposes a typed public surface that dependents compile against. The example plays both roles in one file: a "library" part with explicit types and a consumer.

TypeScript A library surface and its consumer

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript Breaking the contract is an error in the dependent

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

TEXT
tsc --build [project ...] [options]
Flag Description
--verbose Explain why each project is built or skipped.
--dry Show what would be built without building.
--force Rebuild everything, ignoring up-to-date checks.
--clean Delete the outputs of the given projects.
--watch Rebuild affected projects on change.
--stopBuildOnErrors Do not build projects that depend on one that failed.

Behavior: with no argument, it builds the project in the current folder. Up-to-date checks compare file timestamps and .tsbuildinfo data. A project with errors does not emit by default in build mode, so dependents are not built from broken output.

Edge cases: a reference cycle is an error. Only a limited set of flags is accepted in build mode; options that change emit (like --outDir) belong in the tsconfig, not on the command line.

Usage notes

  • Add "references": [{ "path": "../core" }] to the consumer and "composite": true to the library.
  • Use one solution-style root tsconfig.json with "files": [] and a references list, then run tsc -b there.
  • Editors benefit too: go-to-definition lands on source files, not generated .d.ts, when the references are set up.
  • --clean then -b is the reliable fix for confusing stale output.
  • Not the same as tsc -p: -p compiles one project and expects references to be built already.