Watch File Events received over the Network using Listen and execute Gulp Tasks based on it
Last updated 6 years ago by efacilitation .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install watch-network 
SYNC missed versions from official npm registry.

Build Status


Package watch-network
Description Execute tasks based on file events received over the network - gulpfriendly

Scenario: You use Vagrant/VirtualBox in your workflow to have services and configurations in an encapsulated environment. For developing purposes you now sync a local directory into the VM using vboxfs, nfs, rsync or similar. In your VM you want to use watcher facilities for developing-concerns, but for some reason triggering inotify over the network seems to be troublesome or unreliable.

Solution: Based on the Listen Feature "Forwarding file events over TCP" watch-network will connect to a Listen broadcaster as a receiver and watch for File Events. Upon receiving a File Event it will execute tasks based on patterns. Vagrants rsync-auto is based on Listen TCP too.

If you're looking for an alternative Listen implementation in Go, there's GoListen which has also a guide on how you can use it with watch-network.

Setup Listen

Listen Version >= 2.8 required

The listen gem provides the listen executable. So you need to install

gem install listen

or just bundle with the provided Gemfile


To start the listen broadcast process inside your local project directory you then can

listen -v -d .


npm install watch-network


WatchNetwork = require("gulp-watch-network");

watch = WatchNetWork({
  configs: [
      patterns: 'src/*.js',
      tasks: 'something:important',
      onLoad: true

watch.task('something:important', function(changedFile, callback) {
  // `changedFile` which file change caused the task to run
  // `callback` the watcher will wait until you call the callback
  // you can omit both parameters to let the task run synchronously


Usage with Gulp

gulp = require('gulp');
gulp.task('something:important', function() {
  // ..

WatchNetwork = require("gulp-watch-network");

watch = WatchNetWork({
  gulp: gulp,
  configs: [
      patterns: 'src/*.js',
      tasks: ['something:important', 'another:thing']

watch.task('another:thing', function() {
  // ..


Note: If you define a task with the same name on the watcher and on gulp - both will get executed. On the watcher defined tasks execute first.




  • host String Listen Host to connect to (default 'localhost')
  • port String|Number Listen Port to connect to (default 4000)
  • rootFile String Name of the RootFile which determines the basepath (relevant for patterns) (default '.root')
  • flushDeferredTasks Boolean Wether to flush tasks which got deferred while other tasks are already running (default true)
  • gulp Object Gulp Object with defined Tasks which will get executed with run-sequence (default null)
  • configs Array Contains Pattern/Task Configuration Object
    • patterns String|Array Pattern to match against FileChange based on minimatch
    • tasks String|Array Tasks to execute if patterns match
    • onLoad Boolean Wether to execute the tasks once while initialize-Phase (default false)


Initialize the Watcher.


  • callback Function Callback which gets called after the Watcher initialized


Define Task Function which gets executed if patterns match


  • taskName String Name of the task
  • taskFunction Function Task Function


Stops the watcher by destroying the listen socket and removing all event listeners. Be sure to cleanup the watcher instance yourself.


Register Event Listener


  • eventName String Name of the event
  • subscriberFn Function Function which gets called when event fires


watch = WatchNetwork();
watch.on('initialized', function() {
  // ..
watch.on('changed', function(changedFiles) {
  // changedFiles will include *all* changed files

Note: WatchNetwork extends EventEmitter

Available Events

  • initialized Watcher initialized (RootFile-Sync completed)
  • changed Watcher detected file changes, first parameter will include the changed files as an array

Determining Base Path


  • we have a local working directory: /home/wn/work
  • we have a synced version inside the VM: /vagrant

Now if we initialize WatchNetwork inside the VM it does the following:

  • Touch the RootFile (default process.cwd() + rootFile)
  • Wait for FileChange which contains .root
  • Compute RemoteRoothPath (basedir of RootFile): /home/wn/work
  • Initialized.
  • On follow-up FileChanges we will strip the RemoteRootPath
    • Changing /home/wn/work/foo.js
    • What gets matched against the patterns is foo.js then


Licensed under the MIT license.

Current Tags

  • 0.2.4                                ...           latest (6 years ago)

7 Versions

  • 0.2.4                                ...           6 years ago
  • 0.2.3                                ...           6 years ago
  • 0.2.2                                ...           6 years ago
  • 0.2.1                                ...           6 years ago
  • 0.2.0                                ...           6 years ago
  • 0.1.9                                ...           6 years ago
  • 0.1.8                                ...           6 years ago
Maintainers (1)
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 0
Dependencies (4)
Dependents (1)

Copyright 2014 - 2017 © |