How Vite's HMR works — WebSocket-based update propagation

Question

Accepted Answer

Vite's Hot Module Replacement (HMR) system is a cornerstone of its exceptional developer experience, enabling near-instant updates when code changes without full page reloads . **Unlike traditional bundlers that rebuild large portions of the application, Vite leverages native ES modules and a sophisticated WebSocket-based communication layer to achieve precise, fast updates that preserve application state.** At its core, Vite's HMR consists of server-side and client-side components connected via a persistent WebSocket. This channel enables real-time, bidirectional communication . The server broadcasts update notifications, while the client can send custom events for debugging or tooling purposes . The system is designed with security in mind, using cryptographically random tokens to prevent unauthorized WebSocket connections . **File detection:** Vite's file watcher monitors source files; when a change occurs, the handleHMRUpdate function determines the file type and appropriate response . **Module graph analysis:** Vite maintains an EnvironmentModuleGraph tracking dependencies. The propagateUpdate function walks the import chain to find HMR boundaries—modules that have accepted updates . **Boundary detection:** Using a recursive algorithm, the server identifies which modules are affected and whether they can be hot-updated or require a full reload for circular imports . **Payload preparation:** The server constructs an update payload containing module paths and timestamps, then broadcasts via WebSocket . ```json
{
  "type": "update",
  "updates": [
    {
      "type": "js-update",
      "path": "/src/components/Button.jsx",
      "acceptedPath": "/src/components/Button.jsx",
      "timestamp": 1741795200000
    }
  ]
}
```
The update payload contains the changed module path, the accepted path (the module that accepted the HMR), and a timestamp for cache busting when dynamically importing the updated module . The **browser-side HMR client**, injected by Vite during development, maintains a WebSocket connection to the server . When it receives an update payload, it processes each update based on type—JavaScript updates trigger dynamic re-imports with timestamp query parameters, while CSS updates clone `<link>` elements to avoid FOUC . ```js
// The HMR client internally fetches updated modules with cache-busting
const importUrl = `/${path}?t=${timestamp}`;
const newModule = await import(/* @vite-ignore */ importUrl);
```
The timestamp parameter ensures the browser fetches the fresh module instead of using the cached version . Vite exposes the **HMR API** to developers through the **`import.meta.hot`** object, which is only available during development . This API allows modules to declare their HMR acceptance and handle updates gracefully. For Vue or React components, framework integrations automatically handle this, but custom modules can implement their own HMR logic . ```js
// Self-accepting module
if (import.meta.hot) {
  import.meta.hot.accept((newModule) => {
    // Handle updated module
    console.log('Updated:', newModule);
  });
}

// Accepting a dependency
if (import.meta.hot) {
  import.meta.hot.accept('./dependency.js', (newDep) => {
    // Handle dependency update
  });
}

// Cleanup before update
if (import.meta.hot) {
  import.meta.hot.dispose(() => {
    // Remove event listeners, clear intervals
  });
}
```
The API includes `accept()`, `dispose()`, `prune()`, and methods for custom events, giving developers fine-grained control over the HMR lifecycle . **Plugins** can integrate with HMR through the `handleHotUpdate` hook, which allows filtering or modifying affected modules . The system also supports custom WebSocket events—plugins can send and receive arbitrary messages for debugging or tooling purposes . ```js
// vite.config.js
export default {
  plugins: [{
    name: 'custom-hmr',
    handleHotUpdate({ file, modules, read }) {
      // Custom logic to filter or modify affected modules
      return modules.filter(m => m.id?.includes('src'));
    },
    configureServer(server) {
      // Listen for custom events from browser
      server.ws.on('custom-event', (data) => {
        console.log('Browser says:', data);
      });
    }
  }]
}
```
The `handleHotUpdate` hook receives context with the changed file, affected modules, and a file content reader . Speed: Vite's HMR updates typically complete in under 100ms, compared to Webpack's 800ms-1.2s for medium projects . Precision: The module graph allows pinpoint updates without rebuilding unrelated modules . State preservation: Modules can preserve state through HMR boundaries using custom accept handlers . Circular import handling: Vite 5.1+ allows HMR to apply even with circular dependencies, only reloading on actual errors .

How Vite's HMR works — WebSocket-based update propagation

Vite's HMR uses a WebSocket connection between dev server and browser to propagate precise module updates, with the server determining affected modules via its module graph and the client dynamically importing updates while preserving application state

Scenario Questions

Follow-up Questions