Skip to content
Tutorials Center
My learning

Topics

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.

NODE
import fs from "node:fs";

const watcher = fs.watch("./src", (eventType, filename) => {
  console.log(eventType, filename);
});
// later: watcher.close();

Try it

Node.js Watching a directory

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 and debouncing

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
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

  • eventType is 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.
  • filename can be missing. It is not guaranteed on every platform, and it can be null. 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. Use unref(), persistent: false or 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 --watch flag restarts your program on changes without writing any watcher code.