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.
import fs from "node:fs/promises"; for await (const event of fs.watch("./src")) { console.log(event.eventType, event.filename); }
Try it
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.
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
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,returnor an exception closes the underlying watcher. There is nothing to clean up by hand. - Aborting throws. Wrap the loop in
try/catchand checkerr.name === "AbortError", as in the second example. Without a catch, aborting becomes an unhandled rejection. renamemeans more than renaming. The type is reported when a file is created, deleted or renamed.changeusually means the content changed. Platforms differ: one write may produce several events, and a new file often produces bothrenameandchange.- 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.
filenamecan benullor 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
maxQueueevents. If your loop body is slower than the file system, setoverflow: "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.