What does running `tsc --build` (`tsc -b`) do that plain `tsc -p tsconfig.json` does not?

## Two different programs behind one binary `tsc` has two operating modes. The ordinary mode takes a single project — the nearest tsconfig.json, or the one you pass with `-p`/`--project` — reads its file list, type-checks it, and emits. It knows nothing about building anything else. Build mode, entered with `-b` or `--build`, is an orchestrator. It takes one or more projects, follows their `references` arrays transitively to discover the whole dependency graph, orders it topologically, and then runs the ordinary compilation for each project that needs it. ```bash tsc -b packages/app # build app and everything it references tsc -b --verbose # explain each decision tsc -b --clean # delete outputs of the whole graph tsc -b --force # rebuild everything, ignore up-to-date checks tsc -b --watch # keep the graph rebuilding on change ``` ## What happens without build mode Run `tsc -p packages/app/tsconfig.json` in a fresh checkout where `packages/core` has never been compiled and you get an error like: ``` error TS6305: Output file '/repo/packages/core/dist/index.d.ts' has not been built from source file '/repo/packages/core/src/index.ts'. ``` This is the single most instructive error in the whole feature, because it tells you exactly how references work. Project `app` does not type-check `core`'s sources — it resolves imports of `core` to `core`'s **emitted declarations**. If those declarations are missing, the reference cannot be satisfied, and single-project mode has no idea how to produce them. Build mode does: it sees the reference, builds `core` first, and only then compiles `app`. ## The up-to-date check The value of build mode in a repo of any size is not ordering — you could script that — it is skipping. For each project in the graph, build mode decides between three broad outcomes: build it, skip it as up to date, or skip it because only its upstream types changed in ways that do not affect it. The decision draws on two things. The project's `.tsbuildinfo` file records what was compiled and with which compiler version and options. Timestamps compare the project's inputs against its emitted outputs. If an output is older than an input, the project is out of date and gets rebuilt; if the config changed or the compiler version differs from the one recorded, the build info no longer applies and the project is rebuilt too. There is a second-order optimisation worth knowing: after rebuilding an upstream project, build mode compares the freshly emitted declarations with the previous ones. If a change was purely in implementation — a function body edited, no signature moved — the `.d.ts` output is unchanged and downstream projects are left alone. This is why a one-line change deep in a shared package sometimes rebuilds one project and sometimes rebuilds twenty: the difference is whether the public type surface moved. `--verbose` makes all of this legible, printing lines such as "Project 'packages/app' is out of date because output 'dist/index.js' is older than input 'src/index.ts'" — the fastest way to answer "why is this rebuilding again?". ## The build-mode flags `--clean` removes the outputs of every project in the graph, including build-info files; it is the reset button when you suspect the incremental state rather than the code. `--force` builds everything without consulting up-to-date state, which is the safer thing to reach for in a pipeline you do not trust. `--dry` prints the plan without doing anything. `--watch` runs the whole graph in watch mode, rebuilding the affected subgraph on each change rather than restarting from scratch. A practical constraint: in build mode most compiler options cannot be passed on the command line, because each project's settings come from its own tsconfig.json. Build mode accepts its own flags plus a small set of others; anything that changes checking or emit belongs in the config file. ## Where it does and does not help Build mode's job ends at ordering and skipping TypeScript compilations. It does not bundle, does not run tests, and does not know about anything in the repository that is not a referenced TypeScript project. Repos that also need to sequence non-TypeScript steps typically drive `tsc -b` from a task runner rather than expecting it to be one. The payoff is real but bounded: the first build of a graph costs slightly more than a single monolithic compilation, because declarations must be written and read at each boundary. Everything after that is where you win — an edit confined to one leaf package rebuilds one project instead of the world.