Native access to MacOS FSEvents in Node.js

License: MIT

Language: C

fsevents NPM

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.


Supports only Node.js v8.16 and higher.

npm install fsevents


const fsevents = require('fsevents');
const stop = fsevents.watch(__dirname, (path, flags, id) => {
  const info = fsevents.getInfo(path, flags, id);
}); // To start observation
stop(); // To end observation

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 changed
  • flags: number - a numeric value describing what the change was
  • id: string - an unique-id identifying this specific event

Returns 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): FsEventInfo

The 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",
  "path": "file.txt", // {FsEventsEvent}
  "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

Engine compatibility

  • v2 supports node 8.16+
  • v1.2.8 supports node 6+
  • v1.2.7 supports node 4+


The MIT License Copyright (C) 2010-2019 by Philipp Dunkel, Ben Noordhuis, Elan Shankar, Paul Miller — see LICENSE file.

Visit our GitHub page and NPM Page

Project Statistics

Sourcerank 20
Repository Size 176 KB
Stars 374
Forks 79
Watchers 31
Open issues 1
Dependencies 0
Contributors 27
Tags 54
Last updated
Last pushed

Top Contributors See all

Elan Shanker Paul Miller Philipp Dunkel Ben Noordhuis pdunkel Miroslav Bajtoš Chance Jonathan Barnett Henje Aria Stewart Simen Bekkhus Sergey Belov Ali Ijaz Sheikh Elia Schito Artem Medeusheyev papercuptech AJ ONeal fengmk2 Steve Faulkner Shinnosuke Watanabe

Packages Referencing this Repo

Native Access to Mac OS-X FSEvents
Latest release 1.2.11 - Updated - 374 stars
WebJar for fsevents
Latest release 1.0.18-0 - Updated - 374 stars
Native Access to Mac OS-X FSEvents
Latest release 2.1.2 - Updated - 374 stars

Recent Tags See all

v1.2.11 December 13, 2019
v1.2.10 December 13, 2019
2.1.2 November 09, 2019
2.1.1 October 14, 2019
2.1.0 October 01, 2019
v1.2.9 April 29, 2019
v2.0.6 April 16, 2019
v2.0.5 April 16, 2019
v1.2.8 April 16, 2019
v2.0.4 April 16, 2019
v2.0.3 April 01, 2019
v1.2.7 January 18, 2019
v1.2.6 January 15, 2019
v1.2.5 January 15, 2019
v2.0.2-pre-1 December 29, 2018

Something wrong with this page? Make a suggestion

Last synced: 2019-12-14 11:31:14 UTC