The `watch-detector` utility identifies and selects the optimal file watcher mechanism for use with the `sane` library. It prioritizes a valid `watchman` installation on the system, falling back to Node.js's built-in watcher if `watchman` is unavailable or not correctly configured. The current stable version is 1.0.2. Release cadence appears sporadic, with maintenance updates typically driven by upstream `sane` or `watchman` compatibility issues. Its primary differentiator is abstracting the complex logic for choosing between `watchman` and Node's native file system watchers, simplifying `sane` configuration for applications that require robust and performant file monitoring, such as build tools or development servers (e.g., Ember CLI). It aims to provide the best possible performance while offering a reliable fallback, enabling developers to integrate efficient file system observation without needing to implement manual detection logic.
npm install watch-detectorVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to instantiate `WatchDetector`, use it to find the best `sane` watcher option, and then set up a `sane` instance to monitor a directory for changes. It includes a simple file creation to trigger the watcher.
Review `sane`'s error handling and events. Instead of relying on `watch-detector`'s internal warning, monitor the `sane` watcher's lifecycle and potential error events (e.g., 'error' event on the `sane` watcher instance) to detect `watchman` or other watcher failures.
Ensure `watchman` is installed, up-to-date, and correctly configured on the operating system. Check `watchman --version` and refer to the `watchman` documentation for troubleshooting common installation or permission issues. Monitor `sane`'s error events closely.
Do not attempt to configure `watch-detector` to use `fs-events`. Rely on the `watchman` or `node` watcher options as provided by `findBestWatcherOption`. If `fs-events` is critical for your use case, you may need to use `sane` directly and configure `fs-events` manually, bypassing `watch-detector`.
Verify `watchman` is installed and running (`watchman --version`, `watchman status`). Check `watchman` logs for errors. Ensure sufficient system resources (e.g., increase `fs.inotify.max_user_watches` on Linux). Reinstall `watchman` if necessary.
Increase the system limit for file watchers (e.g., on Linux: `echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p`). Consider using `watchman` if not already, as it's more efficient with system resources for large watch sets.