Build Status

Monocle -- a tool for watching things


Have you ever wanted to watch a folder and all of its files/nested folders for changes. well now you can!


npm install monocle


Watch a directory:

var monocle = require('monocle')()
  root: <root directory>,
  fileFilter: <optional>,
  directoryFilter: <optional>,
  listener: fn(fs.stat+ object), //triggered on file change / addition
  complete: <fn> //file watching all set up

The listener will recive an object with the following

  name: <filename>,
  path: <filepath-relative>,
  fullPath: <filepath-absolute>,
  parentDir: <parentDir-relative>,
  fullParentDir: <parentDir-absolute>,
  stat: <see fs.stats>


When a new file is added to the directoy it triggers a file change and thus will be passed to your specified listener.

The two filters are passed through to readdirp. More documentation can be found here

Watch a list of files:

  files: [], //path of file(s)
  listener: <fn(fs.stat+ object)>, //triggered on file / addition
  complete: <fn> //file watching all set up

Just watch path

Just an alias of watchFiles and watchDirectory so you don't need to tell if that's a file or a directory by yourself. Parameter passed to path can be a string or a array of string.

  path: [], //list of paths, or a string of path
  fileFilter: <optional>, // *.js for example
  listener: <fn(fs.stat+ object)>, //triggered on file / addition
  complete: <fn> //file watching all set up

Why not just use ?

  • file watching is really bad cross platforms in node
  • you need to be smart when using as compared to fs.watchFile
  • Monocle takes care of this logic for you!
  • windows systems use
  • osx and linux uses fs.watchFile