Big update!Introducing GitHub Bot Commands. Learn more
Log inBook a demo


Package Overview
File Explorer

Advanced tools


Utilities for watching file trees.


Version published
Weekly downloads
decreased by-12.04%

Weekly downloads



watch -- Utilities for watching file trees in node.js


npm install watch


The intention of this module is provide tools that make managing the watching of file & directory trees easier.

watch.watchTree(root, [options,] callback)

The first argument is the directory root you want to watch.

The options object is passed to fs.watchFile but can also be used to provide two additional watchTree specific options:

  • 'ignoreDotFiles' - When true this option means that when the file tree is walked it will ignore files that being with "."
  • 'filter' - You can use this option to provide a function that returns true or false for each file and directory to decide whether or not that file/directory is included in the watcher.
  • 'interval' - Specifies the interval duration in seconds, the time period between polling for file changes.
  • 'ignoreUnreadableDir' - When true, this options means that when a file can't be read, this file is silently skipped.
  • 'ignoreNotPermitted' - When true, this options means that when a file can't be read due to permission issues, this file is silently skipped.
  • 'ignoreDirectoryPattern' - When a regex pattern is set, e.g. /node_modules/, these directories are silently skipped.

The callback takes 3 arguments. The first is the file that was modified. The second is the current stat object for that file and the third is the previous stat object.

When a file is new the previous stat object is null.

When watchTree is finished walking the tree and adding all the listeners it passes the file hash (keys are the file/directory names and the values are the current stat objects) as the first argument and null as both the previous and current stat object arguments.

watch.watchTree('/home/mikeal', function (f, curr, prev) { if (typeof f == "object" && prev === null && curr === null) { // Finished walking the tree } else if (prev === null) { // f is a new file } else if (curr.nlink === 0) { // f was removed } else { // f was changed } })


Unwatch a previously watched directory root using watch.watchTree.

watch.createMonitor(root, [options,] callback)

This function creates an EventEmitter that gives notifications for different changes that happen to the file and directory tree under the given root argument.

The options object is passed to watch.watchTree.

The callback receives the monitor object.

The monitor object contains a property, files, which is a hash of files and directories as keys with the current stat object as the value.

The monitor has the following events.

  • 'created' - New file has been created. Two arguments, the filename and the stat object.
  • 'removed' - A file has been moved or deleted. Two arguments, the filename and the stat object for the fd.
  • 'changed' - A file has been changed. Three arguments, the filename, the current stat object, and the previous stat object.

The monitor can be stopped using .stop (calls unwatchTree).

var watch = require('watch') watch.createMonitor('/home/mikeal', function (monitor) { monitor.files['/home/mikeal/.zshrc'] // Stat object for my zshrc. monitor.on("created", function (f, stat) { // Handle new files }) monitor.on("changed", function (f, curr, prev) { // Handle file changes }) monitor.on("removed", function (f, stat) { // Handle removed files }) monitor.stop(); // Stop watching })


This module includes a simple command line interface, which you can install with npm install watch -g.

Usage: watch <command> [] [OPTIONS] OPTIONS: --wait=<seconds> Duration, in seconds, that watching will be disabled after running <command>. Setting this option will throttle calls to <command> for the specified duration. --filter=<file> Path to a require-able .js file that exports a filter function to be passed to watchTreeOptions.filter. Path is resolved relative to process.cwd(). --interval=<seconds> Specifies the interval duration in seconds, the time period between polling for file changes. --ignoreDotFiles, -d Ignores dot or hidden files in the watch [directory]. --ignoreUnreadable, -u Silently ignores files that cannot be read within the watch [directory]. --ignoreDirectoryPattern=<regexp>, -p Silently skips directories that match the regular expression.

It will watch the given directories (defaults to the current working directory) with watchTree and run the given command every time a file changes.


As stated above the pattern is:

watch <command> [] [OPTIONS]

To run the watch command in the terminal you have to write the following:

watch 'npm run test -s' directory

As the command has to be written in quotation marks Windows users may need to use double quotes rather than single quotes

watch "npm run test -s" directory

Note: Because Windows users may need to use double quotes rather than single quotes they need to escape the them in npm scripts

"scripts": { "watch:osx": "watch 'npm run test -s' source" "watch:windows": "watch \"npm run test -s\" source", }



On the latest clean master:

npm run release:major npm run release:minor npm run release:patch



What is @cnakazawa/watch?

Utilities for watching file trees.

Is @cnakazawa/watch popular?

The npm package @cnakazawa/watch receives a total of 7,484,193 weekly downloads. As such, @cnakazawa/watch popularity was classified as popular.

Is @cnakazawa/watch well maintained?

We found that @cnakazawa/watch demonstrated a not healthy version release cadence and project activity because the last version was released a year ago.It has 1 open source maintainer collaborating on the project.

Last updated on 11 Feb 2020

Did you know?

Socket installs a Github app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.

Install Socket


Subscribe to our newsletter

Get open source security insights delivered straight into your inbox. Be the first to learn about new features and product updates.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc