Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท The tsc Command Line

tsc --watch

Reference for tsc --watch (-w): how watch mode works, how it reports errors, how to tune file watching, and what to do when it misses changes.

tsc --watch (short form -w) compiles the project once, then keeps running. Whenever a source file changes it re-checks only what is affected and prints the new diagnostics, so feedback usually arrives in a fraction of a second.

Watch mode is best for a terminal that stays open next to your editor, or for development scripts that need fresh .js output while you work.

TEXT
tsc --watch
tsc -w --noEmit
tsc -w --preserveWatchOutput

Try it

Watch mode shows the same diagnostics as a normal run, but repeated. The two examples are what you would see change from one run to the next: a broken edit, then the fixed version.

TypeScript Before the fix

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.

TypeScript After the fix

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

TEXT
tsc --watch [other options]

Related flags, also available under "watchOptions" in tsconfig.json:

Name Description
--preserveWatchOutput Do not clear the screen between runs.
--watchFile Strategy for single files (for example fixedPollingInterval, useFsEvents).
--watchDirectory Strategy for folders (useFsEvents, fixedPollingInterval, dynamicPriorityPolling).
--fallbackPolling Polling style used when native file events are unavailable.
--excludeDirectories, --excludeFiles Stop watching noisy paths such as node_modules.

Command-line values win over tsconfig.json.

Edge cases: changing the tsconfig itself reloads the whole project. Editing a file outside include does nothing. With --build --watch, only the affected projects are rebuilt.

Usage notes

  • Combine with --noEmit when another tool (a dev server, Node's type stripping) already runs your code and you only want type errors.
  • Incremental by design. It keeps the program in memory, which is why it is faster than rerunning tsc after every save.
  • Network folders and containers often deliver no file events. Switch to a polling strategy with watchOptions.
  • Clear output is the default on a terminal; use --preserveWatchOutput to keep history when you need scrollback.
  • Stop with Ctrl+C. The exit code of a stopped watcher is not a build result.
  • Not for CI. A CI job should run once and exit with a status.