Vite's HMR API: Manually Controlling Hot Reloads

Why it exists

To provide a low-level mechanism for frameworks and tools to implement fast, granular updates during development. Instead of reloading the entire page on every file save, Hot Module Replacement (HMR) allows for swapping out only the modules that have changed, preserving application state and speeding up the feedback loop.

The mental model

Think of the HMR API as a set of instructions you give a specific file. You're telling it, "If you or one of your dependencies changes, don't trigger a page refresh. Instead, run this specific function I'm giving you to integrate the new code." This file becomes an "HMR boundary," stopping the update from bubbling up and forcing a reload.

How it works

Vite exposes an API on a special import.meta.hot object, which is only available in development. You use functions like hot.accept() within a module to register a callback. When a dependency changes, Vite sends the new module code to this callback. Your callback code is then responsible for using the new code, for example, by re-rendering a component or updating a variable. This allows a module to be "self-accepting." A module can also accept updates from its direct dependencies without reloading itself.

When to use it

Primarily when you are a framework or library author creating a custom integration with Vite. You might also use it in an application if you have a specific, non-standard piece of code (like a custom data store) that needs to maintain its state across hot reloads and isn't handled by your framework's default HMR logic.

When not to use it

In everyday application development. Frameworks like Vue, React, and Svelte have plugins that handle HMR for you automatically. Manually using this API in components is usually unnecessary and can conflict with the framework's own HMR logic. It is not available in production, so it cannot be used for any production logic.

One canonical example

To make a module update itself, you register a callback that receives the new module version. This code must be wrapped in an if (import.meta.hot) block to ensure it's removed from the production bundle, where import.meta.hot is undefined.

if (import.meta.hot) {
import.meta.hot.accept((newModule) => {
if (newModule) {

// When this file is saved, this code runs. // newModule is the updated version of this file.

console.log('Module updated!', newModule);
}
});
}