Nodejs fs watcher with recursive watch support.

Usage no npm install needed!

<script type="module">
  import akumzyFsWatcher from 'https://cdn.skypack.dev/@akumzy/fs-watcher';



fs-watcher is based on this awesome Go package github.com/radovskyb/watcher for watching for files or directory changes (recursively or non recursively) without using filesystem events, which allows it to work cross platform consistently. @akumzy/fs-watcher is made possible with the help of an IPC packages for Node and Go ipc-node-go and fs-watcher-go


    npm install @akumzy/fs-watcher
    yarn add @akumzy/fs-watcher


  • Customizable polling interval.
  • Filter Events.
  • Watch folders recursively or non-recursively.
  • Choose to ignore hidden files.
  • Choose to ignore specified files and folders.
  • Notifies with some basic informations about the file that the event is based on. e.g
    • name
    • modTime
    • path
    • oldPath if the event is rename or move
    • isDir
    • mode
  • Notifies the full path of the file that the event is based on or the old and new paths if the event was a rename or move event.
  • List the files being watched.


// using require method
const { default: Watcher, Op } = require('@akumzy/fs-watcher')
// or with es modules
import Watcher, { Op } from '@akumzy/fs-watcher'

const w = new Watcher({
  path: '/home/akumzy/Documents', // path you'll like to watch
  debug: true,
  filters: [Op.Create, Op.Write, Op.Rename], // changes to watch default is all
  recursive: true // to watch the specified path recursively
// start watching
w.start((err, files) => {
  if (err) {
  console.log('f', files)
  ;(async () => {
    try {
      let res = await w.ignore('/home/akumzy/Music/Culture')
      console.log('Ignore was ', res ? 'successful' : 'total bs')
      await w.addRecursive('/home/akumzy/Music')
    } catch (error) {
w.onChange('create', file => {
w.onChange('write', file => {
w.onChange('rename', file => {
w.onAll((event, file) => {
  console.log(event, file)


Watcher(option: WatcherOption)


  • interval: number; The polling interval in milliseconds. default is 100ms
  • ignoreHiddenFiles: boolean; to ignore hidden files
  • ignorePaths: string[]; Array of paths to be igored at startup
  • filters: Op[]; changes to subscrib to.
  • binPath?: string; For any reason you want to keep the binary a different location
  • path: string; path to watch
  • recursive: true; if to watch the specified path recursively
  • debug: false;If you're ok with logging from child_process
  • filterHooks: FilterHook[]; Extra filter hooks to be added watcher
    • FilterHook
      • reg: string; reg is simply a plain regular expression pattern eg: ^~$ Good /^~$/ Bad. new RegExp('^~ ) Very bad.
      • useFullPath: boolean If to use the file full path or just the file name


  • start(cb: (err: any, info: EventInfo | FileInfo[]) => void): void; start the watcher

  • getWatchedFiles(): Promise<FileInfo[]>; This return all the watched files per cycle.

  • onChange(event: 'create' | 'remove' | 'rename' | 'chmod' | 'move' | 'write', cb: (file: FileInfo) => void): this; Listen to any change event you want to.

  • onAll(cb: (event: string, file: FileInfo) => void): this; Listens for all change events

  • onError(cb: (error: any) => void): this; Once this event emits it's very likely that the Watcher process has been closed. so is now left for to check and restart

  • stop(): void; stop the Watcher

  • addRecursive(path: string): Promise<boolean>; adds either a single file or directory recursively to the file list.

  • add(path: string): Promise<boolean>; Add path to watch

  • remove(path: string): Promise<boolean>; unwatch path

  • removeRecursive(path: string): Promise<boolean>; unwatch path recursively

  • ignore(paths: string[]): Promise<boolean>; Ignore path


  • size: number; File size in bytes.
  • modTime: Date; File Last modification.
  • path: string; File absolute path
  • name: string; File name with extention if it's not a directory
  • oldPath?: string; empty string if event is not rename or move
  • isDir: boolean; File type which will be true it's a directory
  • mode?: number; File mode


Op {

All credits goes to radovskyb for creatng this github.com/radovskyb/watcher awesome Go package.