“Hot Module Replacement” (HMR) is a feature to inject updated modules into the active runtime.

It’s like LiveReload for every module.

HMR is “opt-in”, so you need to put some code at chosen points of your application. The dependencies are handled by the module system.

I. e. you place your hot replacement code in module A. Module A requires module B and B requires C. If module C is updated, and module B cannot handle the update, modules B and C become outdated. Module A can handle the update and new modules B and C are injected.

Examples

Example 1: hot replace request handler of http server

var requestHandler = require("./handler.js");
var server = require("http").createServer();
server.on("request", requestHandler);
server.listen(8080);
// check if HMR is enabled
if(module.hot) {
    // accept update of dependency
    module.hot.accept("./handler.js", function() {
        // replace request handler of server
        server.removeListener("request", requestHandler);
        requestHandler = require("./handler.js");
        server.on("request", requestHandler);
    });
}

Example 2: hot replace css

// addStyleTag(css: string) => HTMLStyleElement
var addStyleTag = require("./addStyleTag");
var element = addStyleTag(".rule { attr: name }");
module.exports = null;
// check if HMR is enabled
if(module.hot) {
    // accept itself
    module.hot.accept();
    // removeStyleTag(element: HTMLStyleElement) => void
    var removeStyleTag = require("./removeStyleTag");
    // dispose handler
    module.hot.dispose(function() {
        // revoke the side effect
        removeStyleTag(element);
    });
}

API

If HMR is enabled for a module module.hot is an object containing these properties:

accept

accept(dependencies: string[], callback: (updatedDependencies) => void) => void
accept(dependency: string, callback: () => void) => void

Accept code updates for the specified dependencies. The callback is called when dependencies were replaced.

accept([errHandler]) => void

Accept code updates for this module without notification of parents. This should only be used if the module doesn’t export anything. The errHandler can be used to handle errors that occur while loading the updated module.

decline

decline(dependencies: string[]) => void
decline(dependency: string) => void

Do not accept updates for the specified dependencies. If any dependencies is updated, the code update fails with code "decline".

decline() => void

Flag the current module as not update-able. If updated the update code would fail with code "decline".

dispose/addDisposeHandler

dispose(callback: (data: object) => void) => void
addDisposeHandler(callback: (data: object) => void) => void

Add a one time handler, which is executed when the current module code is replaced. Here you should destroy/remove any persistent resource you have claimed/created. If you want to transfer state to the new module, add it to data object. The data will be available at module.hot.data on the new module.

removeDisposeHandler

removeDisposeHandler(callback: (data: object) => void) => void

Remove a handler.

This can useful to add a temporary dispose handler. You could i. e. replace code while in the middle of a multi-step async function.

Management API

Also on the module.hot object.

check

check([autoApply], callback: (err: Error, outdatedModules: Module[]) => void

Throws an exceptions if status() is not idle.

Check all currently loaded modules for updates and apply updates if found.

If no update was found, the callback is called with null.

If autoApply is truthy the callback will be called with all modules that were disposed. apply() is automatically called with autoApply as options parameter.

If autoApply is not set the callback will be called with all modules that will be disposed on apply().

apply

apply([options], callback: (err: Error, outdatedModules: Module[]) => void

If status() != "ready" it throws an error.

Continue the update process.

options can be an object containing these options:

• ignoreUnaccepted: If true the update process continues even if some modules are not accepted (and would bubble to the entry point).

status

status() => string

Return one of idle, check, watch, watch-delay, prepare, ready, dispose, apply, abort or fail.

idle

The HMR is waiting for your call the check(). When you call it the status will change to check.

check

The HMR is checking for updates. If it doesn’t find updates it will change back to idle.

If updates were found it will go through the steps prepare, dispose and apply. Than back to idle.

watch

The HMR is in watch mode and will automatically be notified about changes. After the first change it will change to watch-delay and wait for a specified time to start the update process. Any change will reset the timeout, to accumulate more changes. When the update process is started it will go through the steps prepare, dispose and apply. Than back to watch or watch-delay if changes were detected while updating.

prepare

The HMR is prepare stuff for the update. This may means that it’s downloading something.

ready

An update is available and prepared. Call apply() to continue.

dispose

The HMR is calling the dispose handlers of modules that will be replaced.

apply

The HMR is calling the accept handlers of the parents of replaced modules, than it requires the self accepted modules.

abort

A update cannot apply, but the system is still in a (old) consistent state.

fail

A update has thrown an exception in the middle of the process, and the system is (maybe) in a inconsistent state. The system should be restarted.

status/addStatusHandler

status(callback: (status: string) => void) => void
addStatusHandler(callback: (status: string) => void) => void

Register a callback on status change.

removeStatusHandler

removeStatusHandler(callback: (status: string) => void) => void

Remove a registered status change handler.

How to deal with …

… a module without side effects (the standard case)

Nothing to do in the module. Any parent can accept it.

… a module with side effects

The module needs a dispose handler, then any parent can accept it.

… a module with only side effects and no exports

The module needs a dispose handler and can accept itself. No action is required in the parent.

If the module’s code is not in your hand, the parent can accept the module with some custom dispose logic.

… the application entry module

As it doesn’t export it can accept itself. A dispose handler can pass the application state on replacement.

… external module with not handleable side effects

In the nearest parent you decline the dependency. This makes your application throw on update. But as it’s an external module, an update is very rare.