watchboy

watchboy

Watch files and directories for changes. Fast. No hassle. No native dependencies. Works the same way on Windows, Linux, and MacOS. Low memory usage. Shows you a picture of a dog. It's everything you've ever wanted in a module!

Install

npm install watchboy

Example

const watchboy = require('watchboy');

// watch all files in the current directory, except node modules and dotfiles
const watcher = watchboy(['**/*', '!node_modules/**', '!.*']);

watcher.on('add', ({ path }) => console.log('add:', path));
watcher.on('addDir', ({ path }) => console.log('addDir:', path));
watcher.on('change', ({ path }) => console.log('change:', path));
watcher.on('unlink', ({ path }) => console.log('unlink:', path));
watcher.on('unlinkDir', ({ path }) => console.log('unlinkDir:', path));

watcher.on('ready', () => console.log('all initial files and directories found'));
watcher.on('error', err => console.error('watcher error:', err));

// stop all watching
// watcher can no longer be used and it will no longer fire any events
watcher.close();

API

watchboy(pattern, [options]) → EventEmitter

Watchboy is exposed as a function which returns an event emitter. It takes the following parameters:

• pattern (string|Array<string>): A glob string or array of glob strings to watch, including positive and negative patterns. Directories are also expanded.
• [options] (Object): An optional options object, which contains the following properties:
  • [cwd = process.cwd()] (string): The root directory from which to glob.
  • [persistent = true] (boolean): Whether the process should continue to run as long as files are being watched.

The following events are available on the watcher:

.on('add', ({ path }) => {}) → EventEmitter

Indicates that a new file was added. There is a single argument for this event, which has a path property containing the absolute path for the file that was added.

.on('addDir', ({ path }) => {}) → EventEmitter

Indicates that a new directory was added. There is a single argument for this event, which has a path property containing the absolute path for the directory that was added. Files in this new directory will also be watched according to the provided patterns.

.on('change', ({ path }) => {}) → EventEmitter

Indicates that a file has changed. There is a single argument for this event, which has a path property containing the absolute path for the file that has changed.

.on('unlink', ({ path }) => {}) → EventEmitter

Indicates that a watched file no longer exists. There is a single argument for this event, which has a path property containing the absolute path for the file that no longer exists.

.on('unlinkDir', ({ path }) => {}) → EventEmitter

Indicates that a watched directory no longer exists. There is a single argument for this event, which has a path property containing the absolute path for the directory that no longer exists.

.on('ready', () => {}) → EventEmitter

Indicates that all initial files and directories have been discovered. This even has no arguments. Note that new add and addDir events may fire after this, as new files and directories that match the patterns are created.

.on('error', (err) => {}) → EventEmitter

Indicates that an error has occurred. You must handle this event so that your application does not crash. This error has a single argument: an error which indicates what happened. Aside from standard error properties, there is an additional path property indicating the absolute path of the file or directory which triggered the error.

.close()

Stop watching all files. After this method is called, the watcher can no longer be used and no more events will fire.

Performance

Check out this benchmark comparing watchboy to popular alternatives. Spoiler: it fares really well.