Browserify-HMR

This an implementation of Webpack's Hot Module Replacement API as a plugin for Browserify. This project seems to work in many cases, but it is still early in development and likely has some bugs at the moment. Let me know how it works for you!

Quick Example

git clone https://github.com/Macil/browserify-hmr.git
cd browserify-hmr/example
yarn
yarn start

Open http://localhost:8080/ and try updating label.jsx and interval.js.

Hot Module Replacement Usage

Hot module replacement works by re-executing updated modules. The Hot Module Replacement API must be used to define which modules can accept updates, and what to do when a module is going to be updated.

However, using the HMR API directly in application code is not always the best route. Code transforms and libraries like react-transform-hmr and ud can help do common tasks or entirely automate making certain types of code be hot replaceable.

In addition to the module.hot.* functions from the Webpack Hot Module Replacement API, the following is also implemented:

module.hot.setUpdateMode(mode, options)

This allows the bundle update mode and options to be changed at runtime. mode should be a string and has the same meaning as mode in the Plugin Options section. options is an optional object which may have the properties url, cacheBust, and ignoreUnaccepted, also with the same meanings as the same options in the Plugin Options section. The HMR status must be "idle" when this is called.

Plugin Usage

Add the browserify-hmr plugin to your watchify call:

yarn add --dev browserify-hmr
watchify -p browserify-hmr index.js -o bundle.js

Browserify-HMR works with Node too! Use the m/mode option to tell it to use the "fs" method to update itself. See more information below in the Options section.

watchify --node -p [ browserify-hmr -m fs ] index.js -o bundle.js

Watchify is not required. Browserify can be run multiple times manually instead if more control over the timing of the reloads is desired.

browserify -p [ browserify-hmr -m ajax -u /bundle.js ] index.js -o bundle.js
nano foo.js # make some edits
nano bar.js # edit some more files
browserify -p [ browserify-hmr -m ajax -u /bundle.js ] index.js -o bundle.js

Plugin Options

Browserify-HMR options can be specified from the command line following the plugin name with braces in long or short form:

watchify -p [ browserify-hmr -m fs ] index.js -o bundle.js

Options can be specified using the Browserify API too:

var hmr = require('browserify-hmr');

browserify().plugin(hmr, {
  mode: "fs"
})

m, mode is a string which sets the update mode. "websocket" tells the bundle to open a connection to a websocket server hosted by the plugin to listen for changes. The websocket will be served over HTTP unless any of the tlskey, tlscert, or tlsoptions options are passed. "ajax" uses AJAX requests to download updates. "fs" uses the filesystem module and is suitable for Node use. "none" causes the bundle to not be configured to check for updates. module.hot.setUpdateMode may be called at runtime to reconfigure the bundle. Defaults to "websocket".

supportModes is an optional array of strings specifying other update modes to build support for into the bundle in addition to the given mode. This must be used if the bundle is going to change the update mode by using module.hot.setUpdateMode at runtime to a mode not given in the mode option. You can pass this option on the command like this:

watchify -p [ browserify-hmr -m none --supportModes [ ajax websocket ] ] index.js -o bundle.js

noServe is a boolean which allows Browserify-HMR's automatic websocket server to be disabled. Normally, the Browserify-HMR plugin automatically hosts a websocket server if mode or supportModes contains "websocket". If this is set to true, then the plugin will never host its own websocket server. You could use this if you're building a bundle in websocket mode with the url option set to point to a websocket server hosted by another instance of Browserify-HMR. Defaults to false.

ignoreUnaccepted is a boolean which controls the value of the ignoreUnaccepted parameter to module.hot.apply for the "websocket" mode. (When the "websocket" mode is used, Browserify-HMR automatically checks for updates and applies them, so the application never gets a chance to call module.hot.apply itself.) Defaults to true.

u, url is a string which sets the update URL that the websocket connection or Browserify bundle is accessible at. In "websocket" mode, this defaults to "http://localhost:3123". This is required for the "ajax" mode. This is not required for "fs" mode.

p, port is a number that sets the port to listen on if "websocket" mode is used. If you change this, you'll most likely want to change the url setting too. Defaults to 3123.

h, hostname is the hostname to listen on if "websocket" mode is used. This defaults to "localhost".

b, cacheBust is a boolean which controls whether cache busting should be used for AJAX requests. This only has an effect if the update mode is set to "ajax". If true, then a random parameter is appended to the URL on every request. This allows the cache to be bypassed when the server does not give a low Expires or Cache-Control header value. Note that this prevents E-Tag and Last-Modified headers from being used by the client, so keeping this disabled if it's not needed can be better for performance. You should consider tuning the HTTP headers your script is served with before tweaking this. Defaults to false.

k, key is the bundle key. If multiple bundles built using Browserify-HMR are run within the same javascript environment, then each must have a unique bundle key. The bundle key defaults to a value created by combining the update mode and update url, so you generally don't need to worry about this option.

K, tlskey is the path to the key file to use for HTTPS mode.

C, tlscert is the path to the certificate file to use for HTTPS mode.

tlsoptions is an object of options to pass to the call to https.createServer. Note that this object must be JSONifiable, so use strings instead of any buffers inside of it. This option may not be given by the command line.

disableHostCheck disables Origin and Host header checking when connecting to the server via WebSockets. By default it is set to false to 3rd party websites from connecting to a local websocket and leaking source code. For more information see (NPM Advisory 726)[https://www.npmjs.com/advisories/726].

If you don't use the default websocket update mode, then you'll need to manually tell browserify-hmr when it should check for and apply updates. You can use code like the following somewhere in your project to poll for updates:

if (module.hot) {
  var doCheck = function() {
    module.hot.check(function(err, outdated) {
      if (err) {
        console.error('Check error', err);
      }
      if (outdated) {
        module.hot.apply(function(err, updated) {
          if (err) {
            console.error('Update error', err);
          } else {
            console.log('Replaced modules', updated);
          }
          setTimeout(doCheck, 2000);
        });
      } else {
        setTimeout(doCheck, 2000);
      }
    });
  };
  doCheck();
}

See Also

• react-hot-loader can be used to make React code live-update-able.
• ud and ud-kefir are small simple utilities for declaring data and code as live-updatable.

Planned Work

• There are known bugs currently where changes to modules without update accepters can cause the updates to bubble up to the entry and cause many modules to be reloaded incorrectly.
• The client code is a bit of a mess. It should be refactored and have many smaller unit tests made.