Hot Module Replacement (HMR): How It Works

What is Hot Module Replacement (HMR)?

Hot Module Replacement (HMR) swaps, adds or removes modules in a running application without a full page reload. A dev server pushes the changed module to the browser, which runs the new version and, where it can, keeps state such as form input and the current route. It is a development tool, not a production feature.

How HMR works

The bundler or dev server watches your files and keeps a connection to the page, usually a WebSocket. On a save it recompiles only what changed and sends an update. In webpack the compiler emits an updated manifest plus the changed chunks, and the HMR runtime downloads them and applies them. In Vite the dev server serves native ES modules, so the browser re-imports just the edited module.

HMR needs to know where an update may stop. A module that handles its own updates is an HMR boundary. If the changed module does not accept the update, it bubbles up to the modules that import it. If it reaches the entry point without being accepted, the update fails and the dev server falls back to a full reload. Frameworks wire this up for you (React Fast Refresh, Vue single-file components), so you rarely write it by hand.

Example: a Vite module that accepts updates

// counter.js
let timer = setInterval(tick, 1000)

if (import.meta.hot) {
  import.meta.hot.accept()
  import.meta.hot.dispose(() => clearInterval(timer))
}

Without the dispose handler, every save would start another interval on top of the old one. Vite documents this API on vite.dev; wrapping it in if (import.meta.hot) lets it be tree-shaken from production builds.

HMR vs live reload vs full reload

• Full reload: the page is thrown away and every script runs again, so all state is lost.
• Live reload: reloads the tab automatically on each save, but it is still a full reload.
• HMR: patches only the changed modules, so state usually survives and a CSS edit needs no reload at all.

Common mistakes

• No cleanup. Timers, listeners and subscriptions started at import time leak on every update unless a dispose handler removes them.
• Relying on module-level state. Values kept at module scope can reset on update, so behaviour differs from a fresh load.
• Ignoring unexpected full reloads. They usually mean a module has no accepting boundary above it.
• Trusting dev timings. An app with HMR active is not the app your users get.

HMR, testing and monitoring

HMR only shortens the edit loop. It tells you nothing about how the production build behaves, because the HMR runtime is not part of it. Check the real bundle in a production-like build: Largest Contentful Paint and the rest of Core Web Vitals on a single-page app depend on what you ship, not on how fast you can iterate. Our guide to JavaScript performance covers what to measure, and page speed monitoring tracks it on a schedule once the site is live.

FAQ about Hot Module Replacement

Is HMR the same as live reload?

No. Live reload refreshes the whole page and loses state. HMR replaces only the changed modules in the running page and usually keeps state. It falls back to a full reload when it cannot apply a change safely.

Does HMR run in production?

No. It belongs to the dev server. Production builds do not include the HMR runtime, and the Vite API is written so it can be removed from them.

Why does my app do a full reload even with HMR on?

The changed module, and every module above it, did not accept the update, so it reached the entry point. Check for import-time side effects or an unsupported change to exports.

Which tools support HMR?

webpack and Vite both support it, and frameworks add their own layers on top, such as React Fast Refresh and Vue single-file component HMR. Most starter templates enable it by default.

Does HMR keep component state?

Often, but it is best effort. Editing module-level state or the shape of a component can reset it or trigger a full reload.