November: Procrastination Month

    TypeScript icon, indicating that this package has built-in type declarations

    2.3.2 • Public • Published

    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 =, (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: 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", // {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


    • v2.3 supports Apple Silicon ARM CPUs
    • v2 supports node 8.16+ and reduces package size massively
    • v1.2.8 supports node 6+
    • v1.2.7 supports node 4+


    • I'm getting EBADPLATFORM Unsupported platform for fsevents error.
    • It's fine, nothing is broken. fsevents is macos-only. Other platforms are skipped. If you want to hide this warning, report a bug to NPM bugtracker asking them to hide ebadplatform warnings by default.


    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



    npm i fsevents

    DownloadsWeekly Downloads






    Unpacked Size

    156 kB

    Total Files


    Last publish


    • pipobscure
    • paulmillr