Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท fs and fs/promises

Node.js fs.watchFile() method

Reference for fs.watchFile() and unwatchFile() in Node.js: poll a file with stat at an interval, compare current and previous Stats, and when to prefer fs.watch.

fs.watchFile(filename, listener) checks a file by calling stat on it repeatedly, by default every 5 seconds. Each time the result differs from the previous one, your listener runs with two fs.Stats objects: the current one and the previous one. Because it only compares numbers, it works on any file system, including network drives and container mounts where fs.watch() stays silent.

The price is delay and wasted work: a change is noticed only at the next poll, and every watched file costs a stat call per interval. fs.unwatchFile() stops the polling.

NODE
import fs from "node:fs";

fs.watchFile("app.log", { interval: 1000 }, (curr, prev) => {
  console.log(`size ${prev.size} -> ${curr.size}`);
});

Try it

Node.js Detecting a size change

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 Files that appear and disappear

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.watchFile(filename[, options], listener): fs.StatWatcher
fs.unwatchFile(filename[, listener]): undefined
Name Description
filename The file to poll. A string, Buffer or URL.
options.interval Milliseconds between polls. Default 5007.
options.persistent If false, polling does not keep the process alive. Default true.
options.bigint If true, the Stats objects use bigint numbers. Default false.
listener Called as listener(curr, prev), both fs.Stats. Required.

Returns: a StatWatcher object with ref() and unref() methods.

For unwatchFile(), passing listener removes only that function; omitting it removes every listener on the file and stops polling.

Errors: a missing file is not an error. The listener runs when it appears, with all-zero fields in the "missing" Stats (for example mtimeMs === 0).

Usage notes

  • The interval is a minimum, not a promise. Polling shares the event loop with your other work, so late calls are normal. Set a short interval in tests (30 ms above) and a long one in production.
  • Compare what you care about. The listener fires when any stat field changes, including atime on some systems if the file is read. Check curr.mtimeMs !== prev.mtimeMs or the size before acting.
  • Missing files show zeros. curr.mtimeMs === 0 means "does not exist" (or "no longer"). The listener is also called on the first poll if the file is absent.
  • Changes between polls are merged. Two quick writes within one interval look like one change, and a write-then-revert may not be seen at all.
  • Always call unwatchFile(). Otherwise the timer keeps the process running. unref() or persistent: false avoids this for background checks.
  • Use fs.watch() where it works. It reacts instantly and costs nothing when idle. Pick watchFile() for network shares, some Docker volume mounts and other places where native events do not arrive.
  • One timer per path. Watching the same path twice shares the poller; each listener is still called.
  • No fs/promises version. For async iteration over events use fsPromises.watch().