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
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 .
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 .
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 .
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 .
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 .
