Build a referenced project graph
A repository is split into library, application, and test projects with project references.
TypeScript · Command
tsc --build
tsc --build (or tsc -b) orchestrates TypeScript projects connected by project references. It discovers dependencies, checks freshness, and builds stale projects in dependency order.
- Since
- 3.0
How it works
tsc --build is a build orchestrator for TypeScript project references. It examines the supplied configuration projects, determines which are stale, orders dependencies before dependents, and builds only the projects that need work.
Syntax
tsc --build [projects...] [options]
tsc -b [projects...] [options]Parameters
| Name | Type | Description |
|---|---|---|
projects | string[] | One or more project configuration paths; a directory resolves to its tsconfig.json, and a conventional filename may be omitted. |
Returns
Builds out-of-date referenced projects and their dependencies; with management flags, it can instead report, clean, or force build work.
Key points
- Build mode is designed to operate with project references, making multi-project TypeScript builds faster.
- The build traverses the projects referenced by the supplied configurations.
- Before compiling, it checks which projects already have current outputs.
- Only stale projects are built, and dependency order is respected.
- One invocation can coordinate several project configurations.
-bis the abbreviated spelling of--build.
Common mistakes
- Invoking plain
tscdoes not build referenced dependencies; use--buildwhen the dependency graph must be orchestrated. - Command-line project paths need not be dependency-ordered because TypeScript rearranges them so dependencies build first.
--drypreviews the build without producing the build actions.
Example: Build a project
mkdir -p build && printf '{"compilerOptions":{"composite":true,"outDir":"build"},"include":["src/**/*.ts"]}' > tsconfig.json && mkdir -p src && printf 'export const answer: number = 42;\n' > src/index.ts && tsc --build tsconfig.jsonCreates a composite TypeScript project and builds it with the project build mode.
When to use it
Perform incremental multi-project builds
A large codebase needs to avoid recompiling projects whose outputs are current.
Preview or clean builds
A developer wants to inspect planned work or remove generated outputs.
Interview questions
QWhat does tsc --build do?
It is TypeScript’s project build mode. It finds referenced projects, checks whether they are current, and builds stale projects in dependency order.
Follow-up: How can a build be previewed or forced? Use --dry to show planned work without building, and --force to treat every project as out of date.
QHow do you specify projects?
You can pass several configuration paths, such as tsc -b src test. A tsconfig.json filename can be omitted when the configuration has that conventional name.
Follow-up: What happens if the paths are supplied in the wrong order? TypeScript reorders them so dependencies are built before dependents.
QWhat useful build-mode flags are available?
The command has a short alias: tsc -b. It can also accept build-management flags such as --verbose, --dry, --clean, and --force.
Follow-up: Which option removes generated outputs? --clean deletes outputs for the specified projects and can be combined with --dry.
Related
Project Referencestsconfig.json--verbose--dry--clean--force