Watch Options

TypeScript 3.8 shipped a new strategy for watching directories, which is crucial for efficiently picking up changes to node_modules.

On operating systems like Linux, TypeScript installs directory watchers (as opposed to file watchers) on node_modules and many of its subdirectories to detect changes in dependencies. This is because the number of available file watchers is often eclipsed by the of files in node_modules, whereas there are way fewer directories to track.

Because every project might work better under different strategies, and this new approach might not work well for your workflows, TypeScript 3.8 introduces a new watchOptions field which allows users to tell the compiler/language service which watching strategies should be used to keep track of files and directories.

fallbackPolling - fallbackPolling

When using file system events, this option specifies the polling strategy that gets used when the system runs out of native file watchers and/or doesn’t support native file watchers.

• fixedPollingInterval: Check every file for changes several times a second at a fixed interval.
• priorityPollingInterval: Check every file for changes several times a second, but use heuristics to check certain types of files less frequently than others.
• dynamicPriorityPolling: Use a dynamic queue where less-frequently modified files will be checked less often.

• synchronousWatchDirectory: Disable deferred watching on directories. Deferred watching is useful when lots of file changes might occur at once (e.g. a change in node_modules from running npm install), but you might want to disable it with this flag for some less-common setups.

• Allowed:

  fixedPollingInterval,
  priorityPollingInterval,
  dynamicPriorityPolling

• Released:

  3.8

watchDirectory - watchDirectory

The strategy for how entire directory trees are watched under systems that lack recursive file-watching functionality.

• fixedPollingInterval: Check every directory for changes several times a second at a fixed interval.
• dynamicPriorityPolling: Use a dynamic queue where less-frequently modified directories will be checked less often.

• useFsEvents (the default): Attempt to use the operating system/file system’s native events for directory changes.

• Default:

  useFsEvents

• Allowed:

  fixedPollingInterval,
  dynamicPriorityPolling,
  useFsEvents

• Released:

  3.8

watchFile - watchFile

The strategy for how individual files are watched.

• fixedPollingInterval: Check every file for changes several times a second at a fixed interval.
• priorityPollingInterval: Check every file for changes several times a second, but use heuristics to check certain types of files less frequently than others.
• dynamicPriorityPolling: Use a dynamic queue where less-frequently modified files will be checked less often.
• useFsEvents (the default): Attempt to use the operating system/file system’s native events for file changes.

• useFsEventsOnParentDirectory: Attempt to use the operating system/file system’s native events to listen for changes on a file’s parent directory

• Default:

  useFsEvents

• Allowed:

  fixedPollingInterval,
  priorityPollingInterval,
  dynamicPriorityPolling,
  useFsEvents,
  useFsEventsOnParentDirectory

• Released:

  3.8