TypeScript Reference ยท tsconfig: Projects, Files and Watch Options
TypeScript watchOptions
Reference for the TypeScript watchOptions field: watchFile, watchDirectory, fallbackPolling, excludeDirectories and excludeFiles for tsc --watch.
watchOptions is a top-level tsconfig field (next to compilerOptions) that controls how tsc --watch and editors detect file changes. The defaults use the operating system's file-system events, which is fast and works almost everywhere. You only need these settings when events are unreliable: network drives, containers, virtual machines, or folders with huge numbers of files such as node_modules.
{ "compilerOptions": { "outDir": "dist" }, "watchOptions": { "watchFile": "useFsEvents", "watchDirectory": "useFsEvents", "fallbackPolling": "dynamicPriorityPolling", "excludeDirectories": ["**/node_modules", "dist"] } }
Try it
Watch mode cannot run inside a single file, so the first example types a watch configuration, and the second shows the compiler rejecting a wrong value.
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
{ "watchOptions": { "watchFile": "...", "watchDirectory": "...", "fallbackPolling": "...", "excludeDirectories": [], "excludeFiles": [] } }
| Option | Description |
|---|---|
watchFile |
How single files are watched: fixedPollingInterval, priorityPollingInterval, dynamicPriorityPolling, fixedChunkSizePolling, useFsEvents (default) or useFsEventsOnParentDirectory. |
watchDirectory |
How folder trees are watched: useFsEvents (default), fixedPollingInterval, dynamicPriorityPolling or fixedChunkSizePolling. |
fallbackPolling |
What to do when the system has no native events: fixedPollingInterval, priorityPollingInterval, dynamicPriorityPolling or synchronousWatchDirectory. |
synchronousWatchDirectory |
Disables deferred watching of folders; helps platforms without recursive watching. |
excludeDirectories |
Folders (globs allowed) that are not watched. |
excludeFiles |
Files that are not watched. |
The same settings exist as command-line flags, for example tsc --watch --watchFile useFsEvents.
Usage notes
- Polling costs CPU. Use it only when events fail, and prefer
dynamicPriorityPolling, which checks files that rarely change less often. - Exclude big folders. Listing
node_modulesand build output inexcludeDirectoriesremoves most watcher overhead. - Not part of compilerOptions. Placing
watchOptionsinsidecompilerOptionsis a mistake and is reported as an unknown option. - Inherited with
extends. Like most fields it can come from a base config. - Environment variable.
TSC_WATCHFILEandTSC_WATCHDIRECTORYselect the same strategies from the shell. - Editors read these settings too, so they help when an editor misses saves on a shared folder.