Skip to content
Tutorials Center
My learning

Topics

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.

JSON
{
  "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.

TypeScript A typed watch configuration

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 A mistyped value is caught

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

JSON
{ "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_modules and build output in excludeDirectories removes most watcher overhead.
  • Not part of compilerOptions. Placing watchOptions inside compilerOptions is 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_WATCHFILE and TSC_WATCHDIRECTORY select the same strategies from the shell.
  • Editors read these settings too, so they help when an editor misses saves on a shared folder.