Need help with esm-hmr?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

254 Stars 9 Forks MIT License 59 Commits 12 Opened issues


a Hot Module Replacement (HMR) API for your ESM-based dev server.

Services available


Need anything else?

Contributors list

ESM Hot Module Replacement (ESM-HMR) Spec

_Author: Fred K. Schott (Snowpack), Jovi De Croock (Preact), Evan You (Vue)_
_Status: In Progress_

Hot Module Replacement (HMR) lets your browser live-update individual JavaScript modules in your application during development without triggering a full browser reload or losing the current web application state. This speeds up your development speed with faster updates on every change.

Web bundlers like Webpack, Rollup, and Parcel all implemented different, bundler-specific HMR interfaces. This makes it hard to share HMR integrations across dev environments. As a result, many framework integrations like React Fast Refresh and Preact's Prefresh need to be rewritten for every bundler that they'd like to support. See:


ESM-HMR is a standard HMR API for ESM-based dev environments. The rise of bundle-free development creates the opportunity for a common, standard HMR API built on top of the browser's native module system. ESM-HMR is built for the browser's native module system, so it can be used in any ESM-based dev environment.

Who's Using ESM-HMR?

What's in This Repo?

  1. esm-hmr/client.js
    - A client-side ESM-HMR runtime.
  2. esm-hmr/server.js
    - A server-side ESM-HMR engine to manage connected clients.
  3. An ESM-HMR spec to help your write your own client/server pieces. (coming soon)

Usage Example

export let foo = 1;

if ( { // Receive any updates from the dev server, and update accordingly.{ module }) => { try { foo =; } catch (err) { // If you have trouble accepting an update, mark it as invalid (reload the page).; } }); // Optionally, clean up any side-effects in the module before loading a new copy. => { /* ... */ }); }

ESM-HMR API Overview

All ESM-HMR implementations will follow this API the behavior outlined below. If you have any questions (or would like clarity on some undefined behavior) file an issue and we'll take a look!

if ( {
  // Your HMR code here...
  • If HMR is enabled,
    will be defined.
  • If HMR is disabled (ex: you are building for production),
    should be undefined.
  • You can expect your production build to strip out
    if ( { ... }
    as dead code.
  • Important: You must use the fully expanded
    statement somewhere in the file so that the server can statically check and enable HMR usage.


is the new location for module metadata in ES Modules.

  • Accept HMR updates for this module.
  • When this module is updated, it will be automatically re-imported by the browser.
  • Important: Re-importing an updated module instance doesn't automatically replace the current module instance in your application. If you need to update your current module's exports, you'll need a callback handler.

USE CASE: Your module has no exports, and runs just by being imported (ex: adds a

 element to the page).

accept(handler: ({module: any}) => void)

export let foo = 1;
    module, // An imported instance of the new module
  }) => {
    foo =;
  • Accept HMR updates for this module.
  • Runs the accept handler with the updated module instance.
  • Use this to apply the new module exports to the current application's module instance. This is what accepts your update into the the running application.

This is an important distinction! ESM-HMR never replaces the accepting module for you. Instead, the current module is given an instance of the updated module in the

callback. It's up to the
callback to apply that update to the current module in the current application.

USE CASE: Your module has exports that need to be updated.

accept(deps: string[], handler: ({deps: any[]; module: any;}) => void)

import moduleA from "./modules/a.js";
import moduleB from "./modules/b.js";

export let store = createStore({ a: moduleA, b: moduleB }); ["./modules/a.js", "./modules/b.js"], ({ module, deps }) => { // Get the new store.replaceModules({ a: deps[0].default, b: deps[1].default, }); } );

Sometimes, it's not possible to update an existing module without a reference to its dependencies. If you pass an array of dependency import specifiers to your accept handler, those modules will be available to the callback via the

property. Otherwise, the
property will be empty.

USE CASE: You need a way to reference your dependencies to update the current module.

dispose(callback: () => void)

document.head.appendChild(styleEl); => {


callback executes before a new module is loaded and before
is called. Use this to remove any side-effects and perform any cleanup before loading a second (or third, or forth, or...) copy of your module.

USE CASE: Your module has side-effects that need to be cleaned up.

  • This module is not HMR-compatible.
  • Decline any updates, forcing a full page reload.

USE CASE: Your module cannot accept HMR updates, for example due to permenant side-effects.

invalidate(){ module }) => {
  if (! {;
  • Conditionally invalidate the current module when called.
  • This will reject an in-progress update and force a page reload.

USE CASE: Conditionally reject an update if some condition is met.

export let foo = 1;

if ( { // Recieve data from the dispose() handler{ module }) => { foo = ||; }); // Pass data to the next accept handler call => { = { foo }; }); }

  • You can use
    to pass data from the
    handler(s) to the
  • Defaults to an empty object (
    ) every time an update starts.

Prior Art

This spec wouldn't exist without the prior work of the following projects:

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.