Recursively watch a list of directories & run a command on any file system changes

Features

Extremely lightweight
Simple fs.watch wrapper^†
Runs on macOS, Linux, and Windows
Recursively monitors all subdirectories
Optional ignore patterns

^† While fs.watch has its inconsistencies, efforts are made to normalize behavior across platforms.

Install

$ npm install --save-dev watchlist

Usage

CLI

# Run `npm test` on changes within "src" and "test" contents change
$ watchlist src test -- npm test

# Run `npm test` on changes within "packages", ignoring /fixtures/i
$ watchlist packages --ignore fixtures -- npm test

# Run `lint` script on ANY change
$ watchlist -- npm run lint

API

import { watch } from 'watchlist';

async function task() {
  console.log('~> something updated!');
  await execute_example(); // linter, tests, build, etc
}

// Run `task()` when "{src,test}/**/*" changes
// Must also ignore changes to any `/fixture/i` match
await watch(['src', 'test'], task, {
  ignore: 'fixtures'
});

CLI

The watchlist binary expects the following usage:

$ watchlist [...directory] [options] -- <command>

Important: The -- is required! It separates your command from your watchlist arguments.

Please run watchlist --help for additional information.

API

watch(dirs: string[], handler: Function, options?: Options)

Returns: Promise<void>

Watch a list of directories recursively, calling handler whenever their contents are modified.

dirs

Type: Array<String>

The list of directories to watch.

May be relative or absolute paths.
All paths are resolved from the opts.cwd location.

handler

Type: Function

The callback function to run.

Note: This may be a Promise/async function. Return values are ignored.

options.cwd

Type: String
Default: .

The current working directory. All paths are resolved from this location.
Defaults to process.cwd().

options.ignore

Type: String or RegExp or Array<String | RegExp>

A list of patterns that should not be watched nor should trigger a handler execution.
Ignore patterns are applied to file and directory paths alike.

Note: Any String values will be converted into a RegExp automatically.

options.clear

Type: Boolean
Default: false

Whether or not the console should be cleared before re-running your handler function.

Note: Defaults to true for the CLI! Pass --no-clear to disable.

options.eager

Type: Boolean
Default: false

When enabled, runs the command one time, after watchlist has initialized. When disabled, a change within the dirs list must be observed before the first command execution.

run(command: string, ...args)

Returns: Promise<void>

All arguments to watchlist.run are passed to child_process.exec directly.

Note: Any stdout or stderr content will be piped/forwarded to your console.

command

Type: String

The command string to execute.
View child_process.exec for more information.

args