Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท fs and fs/promises

Node.js fsPromises.watch() method

Reference for fsPromises.watch() in Node.js: watch a file or folder with for await, stop it with an AbortSignal, the recursive option and the limits of change events.

fsPromises.watch(filename) watches a file or directory and returns an async iterator. Each time the operating system reports a change, the iterator yields an object { eventType, filename }. You consume it with for await, which turns a callback-style event source into a plain loop.

It is the promise-flavoured version of fs.watch() and has the same strengths and weaknesses: it is fast because it relies on the operating system, but the events are hints, not a precise log.

NODE
import fs from "node:fs/promises";

for await (const event of fs.watch("./src")) {
  console.log(event.eventType, event.filename);
}

Try it

Node.js Wait for a file to appear

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 process.stdin), it gets the next line from this box.

Node.js Stopping with an AbortSignal

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 process.stdin), it gets the next line from this box.

Syntax

NODE
fsPromises.watch(filename[, options]): AsyncIterator<{ eventType: string, filename: string | Buffer | null }>
Name Description
filename A string, Buffer or URL naming the file or directory to watch.
options.persistent Whether the process stays alive while watching. Default true.
options.recursive Watch all subdirectories too. Default false. Supported on Linux, macOS and Windows in current Node versions.
options.encoding Encoding for the reported file names. Default "utf8".
options.signal An AbortSignal that ends the iteration.
options.maxQueue How many events may wait unread before the overflow rule applies. Default 2048.
options.overflow "ignore" (default, drop and warn) or "throw" when the queue is full.

Returns: an async iterator of event objects. eventType is "rename" or "change".

Errors: ENOENT if the path does not exist when watching starts. An AbortError is thrown out of the loop when the signal aborts.

Usage notes

  • Leaving the loop stops the watch. break, return or an exception closes the underlying watcher. There is nothing to clean up by hand.
  • Aborting throws. Wrap the loop in try/catch and check err.name === "AbortError", as in the second example. Without a catch, aborting becomes an unhandled rejection.
  • rename means more than renaming. The type is reported when a file is created, deleted or renamed. change usually means the content changed. Platforms differ: one write may produce several events, and a new file often produces both rename and change.
  • Debounce. Editors save files in several steps, so react to the first event and wait a short time (for example 50 ms) before reading the file.
  • filename can be null or missing on some platforms and for some events. Do not depend on it for correctness; rescan the directory if you need the truth.
  • Slow consumers lose events. The iterator buffers up to maxQueue events. If your loop body is slower than the file system, set overflow: "throw" to find out instead of silently missing changes.
  • Not for networks or containers. Watching network file systems and some bind mounts may report nothing. Fall back to polling with fs.watchFile() there.
  • Watching a file that is replaced. Many tools save by writing a temporary file and renaming it over the original, which can end the watch on the old file. Watch the containing directory and filter by name instead.