A neat wrapper around node.js fs.watch / fs.watchFile / fsevents.
A neat wrapper around node.js fs.watch / fs.watchFile / fsevents.
Chokidar resolves these problems.
Initially made for brunch (an ultra-swift web app build tool), it is now used in gulp, karma, PM2, browserify, webpack, BrowserSync, Microsoft's Visual Studio Code, and many others. It has proven itself in production environments.
Chokidar does still rely on the Node.js core
fs module, but when using
fs.watchFile for watching, it normalizes the events it
receives, often checking for truth by getting file stats and/or dir contents.
On Mac OS X, chokidar by default uses a native extension exposing the Darwin
FSEvents API. This provides very efficient recursive watching compared with
kqueue available on most *nix platforms. Chokidar still
does have to do some work to normalize the events received that way as well.
On other platforms, the
fs.watch-based implementation is the default, which
avoids polling and keeps CPU usage down. Be advised that chokidar will initiate
watchers recursively for everything within scope of the paths that have been
specified, so be judicious about not wasting system resources by watching much
more than needed.
Install with npm:
npm install chokidar --save
require and use it in your code:
var chokidar = require'chokidar';// One-liner for current directory, ignores .dotfileschokidarwatch'.' ignored: /[\/\\]\./on'all' event path =>console.logevent path;;
// Example of a more typical implementation structure:// Initialize watcher.var watcher = chokidarwatch'file, dir, glob, or array'ignored: /[\/\\]\./persistent: true;// Something to use when events are received.var log = console.logbindconsole;// Add event listeners.watcheron'add' path => log`File has been added`on'change' path => log`File has been changed`on'unlink' path => log`File has been removed`;// More possible events.watcheron'addDir' path => log`Directory has been added`on'unlinkDir' path => log`Directory has been removed`on'error' error => log`Watcher error: `on'ready' => log'Initial scan complete. Ready for changes'on'raw' event path details =>log'Raw event info:' event path details;;// 'add', 'addDir' and 'change' events also receive stat() results as second// argument when available:watcheron'change' path stats =>if stats console.log`File changed size to `;;// Watch new files.watcheradd'new-file';watcheradd'new-file-2' 'new-file-3' '**/other-file*';// Get list of actual paths being watched on the filesystemvar watchedPaths = watchergetWatched;// Un-watch some files.watcherunwatch'new-file*';// Stop watching.watcherclose;// Full list of options. See below for descriptions. (do not use this example)chokidarwatch'file'persistent: trueignored: '*.txt'ignoreInitial: falsefollowSymlinks: truecwd: '.'usePolling: trueinterval: 100binaryInterval: 300alwaysStat: falsedepth: 99awaitWriteFinish:stabilityThreshold: 2000pollInterval: 100ignorePermissionErrors: falseatomic: true // or a custom 'atomicity delay', in milliseconds (default 100);
paths(string or array of strings). Paths to files, dirs to be watched recursively, or glob patterns.
options(object) Options object as defined below:
true). Indicates whether the process should continue to run as long as files are being watched. If set to
fseventsto watch, no more events will be emitted after
ready, even if the process continues to run.
ignored(anymatch-compatible definition) Defines files/paths to be ignored. The whole relative or absolute path is tested, not just filename. If a function with two arguments is provided, it gets called twice per path - once with a single argument (the path), second time with two arguments (the path and the
fs.Statsobject of that path).
false). If set to
addDirevents are also emitted for matching paths while instantiating the watching as chokidar discovers these file paths (before the
false, only the symlinks themselves will be watched for changes instead of following the link references and bubbling events through the link's path.
cwd(no default). The base directory from which watch
pathsare to be derived. Paths emitted with events will be relative to this.
false). Whether to use fs.watchFile (backed by polling), or fs.watch. If polling leads to high CPU utilization, consider setting this to
false. It is typically necessary to set this to
trueto successfully watch files over a network, and it may be necessary to successfully watch files in other non-standard situations. Setting to
trueexplicitly on OS X overrides the
100). Interval of file system polling.
300). Interval of file system polling for binary files. (see list of binary extensions)
trueon OS X). Whether to use the
fseventswatching interface if available. When set to
fseventsis available this supercedes the
usePollingsetting. When set to
falseon OS X,
usePolling: truebecomes the default.
false). If relying upon the
fs.Statsobject that may get passed with
changeevents, set this to
trueto ensure it is provided even in cases where it wasn't already available from the underlying watch events.
undefined). If set, limits how many levels of subdirectories will be traversed.
false). By default, the
addevent will fire when a file first appear on disk, before the entire file has been written. Furthermore, in some cases some
changeevents will be emitted while the file is being written. In some cases, especially when watching for large files there will be a need to wait for the write operation to finish before responding to a file creation or modification. Setting
true(or a truthy value) will poll file size, holding its
changeevents until the size does not change for a configurable amount of time. The appropriate duration setting is heavily dependent on the OS and hardware. For accurate detection this parameter should be relatively high, making file watching much less responsive. Use with caution.
options.awaitWriteFinishcan be set to an object in order to adjust timing params:
awaitWriteFinish.stabilityThreshold(default: 2000). Amount of time in milliseconds for a file size to remain constant before emitting its event.
awaitWriteFinish.pollInterval(default: 100). File size polling interval.
false). Indicates whether to watch files that don't have read permissions if possible. If watching fails due to
EACCESwith this set to
true, the errors will be suppressed silently.
false). Automatically filters out artifacts that occur when using editors that use "atomic writes" instead of writing directly to the source file. If a file is re-added within 100 ms of being deleted, Chokidar emits a
changeevent rather than
add. If the default of 100 ms does not work well for you, you can override it by setting
atomicto a custom value, in milliseconds.
chokidar.watch() produces an instance of
FSWatcher. Methods of
.add(path / paths): Add files, directories, or glob patterns for tracking. Takes an array of strings or just one string.
.on(event, callback): Listen for an FS event. Available events:
allis available which gets emitted with the underlying event name and path for every event other than
.unwatch(path / paths): Stop watching files, directories, or glob patterns. Takes an array of strings or just one string.
.close(): Removes all listeners from watched files.
.getWatched(): Returns an object representing all the paths on the file system being watched by this
FSWatcherinstance. The object's keys are all the directories (using absolute paths unless the
cwdoption was used), and the values are arrays of the names of the items contained in each directory.
If you need a CLI interface for your file watching, check out chokidar-cli, allowing you to execute a command on each change, or get a stdio stream of change events.
npm WARN optional dep failed, continuing email@example.com
npmhandles optional dependencies and is not indicative of a problem. Even if accompanied by other related error messages, Chokidar should function properly.
ERR! stack Error: Python executable "python" is v3.4.1, which is not supported by gyp.
npm config set python python2.7
gyp ERR! stack Error: not found: make
The MIT license.
Copyright (c) 2012 - 2016 Paul Miller paulmillr.com & Elan Shanker
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.