gaze
A globbing fs.watch wrapper for Node.js that combines the best features of other file-watching libraries.
What is gaze?
Gaze is a file-watching library for Node.js that provides a glob pattern-based wrapper around the native `fs.watch` API. It solves the problem of unreliable or limited file system monitoring by offering a robust, cross-platform solution that aggregates the best features from other popular watch libraries. Developers use it to track file changes, additions, deletions, and renames in real-time during development or build processes.
Node.js developers who need reliable file system monitoring for tasks like live reloading, build automation, or development tooling. It's particularly useful for those working in cross-platform environments or requiring advanced glob pattern matching.
Developers choose Gaze because it combines the reliability and features of multiple watch libraries into a single, well-tested package. Its cross-platform compatibility, flexible event system, and dynamic pattern management make it a versatile choice over basic `fs.watch` implementations or more limited alternatives.
Overview
:crystal_ball: A globbing fs.watch wrapper built from the best parts of other fine watch libs.
Use Cases
Best For
- Setting up live reloading for development servers
- Automating build processes when source files change
- Monitoring log files or directories for real-time updates
- Creating custom development tools that react to file system events
- Watching multiple file types with complex glob patterns
- Cross-platform development environments requiring consistent file watching
Not Ideal For
- Applications requiring sub-millisecond latency for high-frequency file changes, as polling or native watch modes can introduce delays.
- Modern Node.js projects exclusively using ES modules, since Gaze is CommonJS-based and lacks official ES module support.
- Teams seeking a minimal, zero-dependency file watcher, given Gaze's dependencies and feature-rich setup that may be overkill for simple use cases.
- Environments where only basic, non-glob file watching is needed, making native `fs.watch` a lighter alternative.
Pros & Cons
Pros
Works consistently on Windows, macOS, and Linux with Node.js >= 4.x, as stated in the README, eliminating platform-specific quirks found in native `fs.watch`.
Supports complex glob patterns like `**/*.js` using `minimatch`, allowing precise file matching without manual filtering, as highlighted in the documentation.
Emits detailed events for added, changed, deleted, and renamed files, plus an aggregated 'all' event, making it easy to track and respond to changes accurately.
Allows adding or removing file patterns dynamically with the `add` and `remove` methods while the watcher is running, offering flexibility during operation.
Cons
Last release was in 2018 (version 1.1.3), indicating potential lack of updates, bug fixes, or compatibility with newer Node.js versions beyond the stated >=4.x support.
Polling mode (`mode: 'poll'`) can be resource-intensive with many files, and even native mode may have delays or issues like `ENOENT` errors, as acknowledged in the release history.
Requires understanding of options like `mode`, `interval`, and `debounceDelay`, which can be confusing for quick setup compared to simpler, more modern alternatives.
Frequently Asked Questions
Related Projects
lobe-chatThe ultimate space for work and life — to find, build, and collaborate with agent teammates that grow with you. We are taking agent harness to the next level — enabling multi-agent collaboration, effortless agent team design, and introducing agents as the unit of work interaction.
nerd-fontsIconic font aggregator, collection, & patcher. 3,600+ icons, 50+ patched fonts: Hack, Source Code Pro, more. Glyph collections: Font Awesome, Material Design Icons, Octicons, & more
httpie🥧 HTTPie CLI — modern, user-friendly command-line HTTP client for the API era. JSON support, colors, sessions, downloads, plugins & more.
sniffnetComfortably monitor your Internet traffic 🕵️♂️
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.