The fsevents npm package is a Node.js module that provides native and efficient file system event watching on macOS. It is designed to be used by Node.js applications to receive notifications when the contents of a directory change, including file creations, modifications, and deletions. It leverages the macOS FSEvents API for optimal performance and accuracy.
Watching for file changes
This feature allows you to watch a directory for changes and execute a callback function whenever a change is detected. The callback receives the path of the changed file, flags that describe the change, and an event ID.
const fsevents = require('fsevents');
const watcher = fsevents.watch('/path/to/dir', (path, flags, id) => {
console.log('File changed:', path);
});
watcher.start();Stopping the watcher
This feature allows you to stop watching for file changes. It is useful when you no longer need to monitor a directory or when your application is shutting down.
watcher.stop();Chokidar is a file watching package that works across multiple platforms, including macOS, Windows, and Linux. It provides a high-level API for file system notifications and is often used as an alternative to fsevents for cross-platform compatibility. Chokidar uses fsevents on macOS for performance but falls back to other methods on other operating systems.
The watch package is another file system watcher for Node.js. It is less efficient than fsevents because it uses polling to detect changes rather than native file system events. This can result in higher CPU usage and less immediate change detection compared to fsevents.
Node-watch is a simple and lightweight file watching library. Like chokidar, it aims to provide a consistent API across different platforms. It does not rely on native extensions, which can make it easier to install than fsevents, but it may not offer the same level of performance on macOS.
Native access to MacOS FSEvents in Node.js
The FSEvents API in MacOS allows applications to register for notifications of changes to a given directory tree. It is a very fast and lightweight alternative to kqueue.
This is a low-level library. For a cross-platform file watching module that uses fsevents, check out Chokidar.
npm install fsevents
Supports only Node.js v8.16 and higher.
const fsevents = require('fsevents');
// To start observation
const stop = fsevents.watch(__dirname, (path, flags, id) => {
const info = fsevents.getInfo(path, flags);
});
// To end observation
stop();
Important note: The API behaviour is slightly different from typical JS APIs. The
stopfunction must be retrieved and stored somewhere, even if you don't plan to stop the watcher. If you forget it, the garbage collector will eventually kick in, the watcher will be unregistered, and your callbacks won't be called anymore.
The callback passed as the second parameter to .watch get's called whenever the operating system detects a
a change in the file system. It takes three arguments:
fsevents.watch(dirname: string, (path: string, flags: number, id: string) => void): () => Promise<undefined>path: string - the item in the filesystem that have been changedflags: number - a numeric value describing what the change wasid: string - an unique-id identifying this specific eventReturns closer callback which when called returns a Promise resolving when the watcher process has been shut down.
fsevents.getInfo(path: string, flags: number, id: string): FsEventInfoThe getInfo function takes the path, flags and id arguments and converts those parameters into a structure
that is easier to digest to determine what the change was.
The FsEventsInfo has the following shape:
/**
* @typedef {'created'|'modified'|'deleted'|'moved'|'root-changed'|'cloned'|'unknown'} FsEventsEvent
* @typedef {'file'|'directory'|'symlink'} FsEventsType
*/
{
"event": "created", // {FsEventsEvent}
"path": "file.txt",
"type": "file", // {FsEventsType}
"changes": {
"inode": true, // Had iNode Meta-Information changed
"finder": false, // Had Finder Meta-Data changed
"access": false, // Had access permissions changed
"xattrs": false // Had xAttributes changed
},
"flags": 0x100000000
}
EBADPLATFORM Unsupported platform for fsevents error.The MIT License Copyright (C) 2010-2020 by Philipp Dunkel, Ben Noordhuis, Elan Shankar, Paul Miller — see LICENSE file.
Visit our GitHub page and NPM Page
FAQs
Native Access to MacOS FSEvents
The npm package fsevents receives a total of 13,654,299 weekly downloads. As such, fsevents popularity was classified as popular.
We found that fsevents demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.