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.
import fs from "node:fs"; fs.watchFile("app.log", { interval: 1000 }, (curr, prev) => { console.log(`size ${prev.size} -> ${curr.size}`); });
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.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
statfield changes, includingatimeon some systems if the file is read. Checkcurr.mtimeMs !== prev.mtimeMsor the size before acting. - Missing files show zeros.
curr.mtimeMs === 0means "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()orpersistent: falseavoids this for background checks. - Use
fs.watch()where it works. It reacts instantly and costs nothing when idle. PickwatchFile()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/promisesversion. For async iteration over events usefsPromises.watch().