watchify

watch mode for browserify builds

Update any source file and your browserify bundle will be recompiled on the spot.

example

1

$ watchify main.js -o static/bundle.js

Now as you update files, static/bundle.js will be automatically incrementally rebuilt on the fly.

The -o option can be a file or a shell command (not available on Windows) that receives piped input:

1

watchify main.js -o 'exorcist static/bundle.js.map > static/bundle.js' -d

1

watchify main.js -o 'uglifyjs -cm > static/bundle.min.js'

You can use -v to get more verbose output to show when a file was written and how long the bundling took (in seconds):

1
2
3
4
5
6
7

$ watchify browser.js -d -o static/bundle.js -v
610598 bytes written to static/bundle.js (0.23 seconds)
610606 bytes written to static/bundle.js (0.10 seconds)
610597 bytes written to static/bundle.js (0.14 seconds)
610606 bytes written to static/bundle.js (0.08 seconds)
610597 bytes written to static/bundle.js (0.08 seconds)
610597 bytes written to static/bundle.js (0.19 seconds)

usage

Use watchify with all the same options as browserify except that -o (or --outfile) is mandatory. Additionally, there are also:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

Standard Options:

  --outfile=FILE, -o FILE

    This option is required. Write the browserify bundle to this file. If
    the file contains the operators `|` or `>`, it will be treated as a
    shell command, and the output will be piped to it.

  --verbose, -v                     [default: false]

    Show when a file was written and how long the bundling took (in
    seconds).

  --version

    Show the watchify and browserify versions with their module paths.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

Advanced Options:

  --delay                           [default: 600]

    Amount of time in milliseconds to wait before emitting an "update"
    event after a change.

  --ignore-watch=GLOB, --iw GLOB    [default: false]

    Ignore monitoring files for changes that match the pattern. Omitting
    the pattern will default to "**/node_modules/**".

  --poll=INTERVAL                   [default: false]

    Use polling to monitor for changes. Omitting the interval will default
    to 100ms. This option is useful if you're watching an NFS volume.

methods

1

var watchify = require('watchify');

watchify(b, opts)

watchify is a browserify plugin, so it can be applied like any other plugin. However, when creating the browserify instance b, you MUST set the cache and packageCache properties:

1
2

var b = browserify({ cache: {}, packageCache: {} });
b.plugin(watchify);

1
2
3
4
5

var b = browserify({
  cache: {},
  packageCache: {},
  plugin: [watchify]
});

By default, watchify doesn't display any output, see events for more info.

b continues to behave like a browserify instance except that it caches file contents and emits an 'update' event when a file changes. You should call b.bundle() after the 'update' event fires to generate a new bundle. Calling b.bundle() extra times past the first time will be much faster due to caching.

Important: Watchify will not emit 'update' events until you've called w.bundle() once and completely drained the stream it returns.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

var fs = require('fs');
var browserify = require('browserify');
var watchify = require('watchify');

var b = browserify({
  entries: ['path/to/entry.js'],
  cache: {},
  packageCache: {},
  plugin: [watchify]
});

b.on('update', bundle);
bundle();

function bundle() {
  b.bundle().pipe(fs.createWriteStream('output.js'));
}

options

You can to pass an additional options object as a second parameter of watchify. Its properties are:

opts.delay is the amount of time in milliseconds to wait before emitting an "update" event after a change. Defaults to 100.

opts.ignoreWatch ignores monitoring files for changes. If set to true, then **/node_modules/** will be ignored. For other possible values see Chokidar's documentation on "ignored".

opts.poll enables polling to monitor for changes. If set to true, then a polling interval of 100ms is used. If set to a number, then that amount of milliseconds will be the polling interval. For more info see Chokidar's documentation on "usePolling" and "interval". This option is useful if you're watching an NFS volume.

1
2
3
4
5
6
7

var b = browserify({ cache: {}, packageCache: {} });
// watchify defaults:
b.plugin(bundle, {
  delay: 100,
  ignoreWatch: ['**/node_modules/**'],
  poll: false
});

b.close()

Close all the open watch handles.

events

b.on('update', function (ids) {})

When the bundle changes, emit the array of bundle ids that changed.

b.on('bytes', function (bytes) {})

When a bundle is generated, this event fires with the number of bytes.

b.on('time', function (time) {})

When a bundle is generated, this event fires with the time it took to create the bundle in milliseconds.

b.on('log', function (msg) {})

This event fires after a bundle was created with messages of the form:

1

X bytes written (Y seconds)

with the number of bytes in the bundle X and the time in seconds Y.

install

With npm do:

1

$ npm install -g watchify

to get the watchify command and:

1

$ npm install watchify

to get just the library.

troubleshooting

rebuilds on OS X never trigger

It may be related to a bug in fsevents (see #250 and stackoverflow). Try the --poll flag and/or renaming the project's directory - that might help.

license

MIT