Node.js Reference ยท fs and fs/promises
Node.js fs.watch() method
Reference for fs.watch() in Node.js: listen for file and folder changes, event types, the recursive and signal options, platform quirks and debouncing.
fs.watch(filename[, options][, listener]) asks the operating system to tell you when a file or directory changes. It returns an FSWatcher, an event emitter that fires "change" with an event type ("change" or "rename") and the name of the file involved. Because the operating system does the work, it costs almost nothing while idle, unlike fs.watchFile(), which polls.
The API is a thin layer over inotify (Linux), FSEvents (macOS) and ReadDirectoryChangesW (Windows), and their behavior differs. Treat events as hints that "something happened here" and re-read the state yourself.
import fs from "node:fs"; const watcher = fs.watch("./src", (eventType, filename) => { console.log(eventType, filename); }); // later: watcher.close();
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
fs.watch(filename[, options][, listener]): fs.FSWatcher
| Name | Description |
|---|---|
filename |
A file or directory path (string, Buffer or URL). |
options.persistent |
If false, the watcher does not keep the process alive. Default true. |
options.recursive |
Watch subdirectories too. Supported on Linux, macOS and Windows in current Node.js versions. Default false. |
options.encoding |
How filename is delivered. Default "utf8". |
options.signal |
An AbortSignal that closes the watcher when aborted. |
listener |
Called as listener(eventType, filename). Same as adding a "change" handler. |
Events on the FSWatcher: "change" (eventType, filename), "close", and "error" (err). Methods: close(), ref(), unref().
Errors: ENOENT is thrown if the path does not exist when you start watching. ENOSPC or EMFILE means the system watch limit was reached.
Usage notes
eventTypeis coarse."rename"means a name appeared, vanished or was renamed;"change"means content or metadata changed. Creating a file often gives both. Do not build logic on the exact sequence.filenamecan be missing. It is not guaranteed on every platform, and it can benull. Handle that case.- One save, several events. Editors write temporary files, rename and touch metadata. Debounce with a short timer and then read the real state, as in the second example.
- Watch the directory, not the file, if the file may be replaced by rename (many editors do this). A watcher on a single path can stop receiving events once its inode is replaced.
- Always handle
"error". An unhandled error event on the watcher crashes the process, for example when the watched folder is deleted. - Remember to
close(). A persistent watcher keeps Node running. Useunref(),persistent: falseor a signal for background watchers. - Network and container volumes often deliver no events at all. Use
fs.watchFile()there. - Async iteration:
fsPromises.watch()gives the same events as an async iterable. - The built-in
node --watchflag restarts your program on changes without writing any watcher code.