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.
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.
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.
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
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": trueto the library. - Use one solution-style root
tsconfig.jsonwith"files": []and areferenceslist, then runtsc -bthere. - Editors benefit too: go-to-definition lands on source files, not generated
.d.ts, when the references are set up. --cleanthen-bis the reliable fix for confusing stale output.- Not the same as
tsc -p:-pcompiles one project and expects references to be built already.
Related
- composite
- references
- incremental
- Tutorial: Large projects, Monorepos