fs-watch-file

This module is a very thin wrapper around fs.watch with a focus on allowing you to watch only specific files for changes. This module is not meant as a complete file watching solution -- for that, you may want to look at watchboy. Instead, if you would like to watch already known files (perhaps you already globbed them on your own) amd would like to do so in a cross-platform way with no dependencies, then this module might be for you.

Install

npm install fs-watch-file

Usage

const watch = require('fs-watch-file');
const watcher = watch({ persistent: false });

// add paths to already-known files
watcher.add('/path/to/file/one');
watcher.add('/path/to/file/two');
watcher.add('/path/to/file/three');

// get notified on changes
watcher.on('change', ev => {
  console.log(`file changed: ${ev.filepath}`);
});

// get notified on errors
watcher.on('error', err => {
  console.log(`file no longer being watched: ${err.filepath}`);

  // optionally, go ahead and add a watcher again
  watcher.add(err.filepath);
});

// stop watching everything
watcher.close();

watcher options

• [persistent = true] {boolean}: this maps to node's fs.watch(filename, { persistent }) option, and defined whether the file watcher should keep the process alive or not

add(filepath)

This method adds a watcher for a specific file. The exact filepath value will be passed into fs.watch and will also be used when change or error events are triggered.

remove(filepath)

This method removes the watcher for a specific file. The exact filepath value is used to match existing watchers.

close()

Stop all file watching. No more events will be fired after this is called. You are free to add more files to be watched after this.

Events

You can use on, once, and off to add event listeners as you would expect. The following events are triggered:

• change: A file has changed. This event has a single object as its argument, with the following properties:
  • filepath: the argument passed into watcher.add
• error: An unexpected thing has happened and the file will no longer be watched. This event has a single Error as its argument, with the following properties:
  • code: a unique error code, either UnexpectedClose or UnexpectedError
  • filepath: the argument passed into watcher.add