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 yourcommand
from yourwatchlist
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 aRegExp
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
orstderr
content will be piped/forwarded to your console.
command
Type: String
The command string to execute.
View child_process.exec
for more information.
args
Type: String
Additional child_process.exec
arguments.
Important: The
callback
argument is not available!
License
MIT Β© Luke Edwards