Interactive development
A developer edits TypeScript files and wants automatic recompilation and diagnostics.
TypeScript · Command
tsc --watch
tsc --watch keeps the TypeScript compiler running and monitors input files for changes. Configure its file and directory-watching behavior with watch-related compiler options or watchOptions in tsconfig.json.
How it works
Run tsc --watch to keep the TypeScript compiler active while it monitors the project’s input files. When changes are detected, it recompiles and reports diagnostics; watch behavior can be adjusted through watchOptions in tsconfig.json or related watch flags.
Syntax
tsc --watch [options]Parameters
| Name | Type | Description |
|---|---|---|
--watch | boolean | Enables watch mode so the compiler monitors input files. |
Returns
A continuously running compiler process that watches input files and recompiles when changes are detected.
Key points
- The command keeps the compiler in a long-running mode that monitors the files participating in the compilation.
- Project-specific watch behavior is configured in the
watchOptionssection of tsconfig.json. - TypeScript’s watcher uses Node.js file-watching APIs rather than implementing an independent operating-system watcher.
- One available strategy watches parent directories, trading lower CPU usage for potentially lower accuracy.
- Dynamic priority polling gives frequently changed files shorter polling intervals and reduces attention to unchanged files.
Common mistakes
- Polling-based watching can consume CPU, so choose watch settings according to the reliability and resource trade-offs of the environment.
Example: Watch a configured project
tsc --watch --project tsconfig.jsonRuns the TypeScript compiler in watch mode for the project described by tsconfig.json; keep the process running and edit an input file to trigger recompilation.
When to use it
Continuous local builds
A project needs compiler output to stay current during a long-running local process.
Watch tuning for large codebases
A large repository needs platform-specific watcher strategies or exclusions.
Interview questions
QWhat does tsc --watch do?
--watch keeps the compiler running and watches input files for changes. The compiler then responds to detected changes instead of requiring a separate command for every edit.
Follow-up: How can watch behavior be configured? Use the watchOptions section in tsconfig.json, or the corresponding watch-related compiler options.
QWhich mechanisms does TypeScript use for watching?
The implementation relies on Node’s fs.watch and fs.watchFile. Native file-system events can be efficient, while polling is generally more reliable but uses CPU cycles.
Follow-up: What is the default file-watching strategy? The documentation identifies useFsEvents as the default strategy in the watch configuration options.
QHow can a large codebase tune watch mode?
watchOptions can control how files and directories are watched, including file strategy, directory strategy, fallback polling, and whether directory watching is synchronous. This lets a project adapt watch behavior to its platform and workload.
Follow-up: When is a fallback useful? It can provide an alternative when native watchers cannot be created or when the platform limits active watches.
Related
watchOptionswatchFilewatchDirectoryfallbackPollingsynchronousWatchDirectorypreserveWatchOutputexcludeDirectoriesexcludeFiles