tsc --build: Project References Builds
tsc --build (tsc -b) compiles a set of referenced TypeScript projects in the correct order, rebuilding only what changed.
Monorepos wire packages together with project references. tsc --build is the mode that understands them, builds in dependency order, and caches incrementally.
What it does
tsc --build reads a solution tsconfig with references, computes the build order, and compiles each project, skipping ones whose inputs are unchanged via .tsbuildinfo. It emits declaration files so downstream projects can consume upstream types.
Common usage
tsc --build
tsc -b tsconfig.build.json
# force a full rebuild / clean outputs
tsc -b --force
tsc -b --cleanOptions
| Flag | What it does |
|---|---|
| -b, --build | Build project references in order |
| --clean | Delete outputs of referenced projects |
| --force | Rebuild everything, ignoring the incremental cache |
| --verbose | Log why each project is or is not rebuilt |
| --dry | Show what would be built without building |
In CI
Referenced projects must set "composite": true and emit declarations, or the build fails. Cache the .tsbuildinfo files to keep incremental builds fast; if a stale cache causes phantom pass/fail, use --force. Run --clean before a release build to avoid stale outputs.
Common errors in CI
"error TS6306: Referenced project \"...\" must have setting \"composite\": true" means a referenced tsconfig is missing composite. "error TS6305: Output file \"...\" has not been built from source file ..." means a referenced project was not built first (run tsc -b at the root). "error TS6307: File is not listed within the file list of project" means an include glob omits a referenced source.