skip to content

Dev Server & HMR

Vite's dev server transforms each module on request, and import.meta.hot's accept, dispose and invalidate decide whether an edit swaps in place or reloads. Interviewers ask why every save reloads.

on this pageshow

questions

6

In Vite's dev server, why does saving a file sometimes reload the whole page instead of hot-updating, and how do you tell which cause fired?

level: middleimportance: must knowfreq 24%

answer

  1. read the terminal line after the save
  2. nobody agreed to take the update
  3. the HTML template and the config
  4. restart drops the socket, then reload
  5. a debug flag and a browser event

basics

~20 s

Vite reloads when no module between the edited file and the entry accepts the update, when index.html changes, or when a config or .env change restarts the server. The terminal's page reload line and vite --debug hmr show which.

solid answer

~50 s

After a save, Vite looks for a module on the path from the edited file up to the entry that called `import.meta.hot.accept`. If the walk reaches a module with no importers without finding one, it sends a full reload and logs `page reload <file>`; a plain utility imported by `main.ts` is the usual case. Editing the `index.html` page template reloads, because it cannot be hot-updated. Editing `vite.config.*`, a file the config imports, or one of the mode's `.env` files restarts the server (`… changed, restarting server...`), and the browser reloads once it reconnects. A module that calls `import.meta.hot.invalidate()` passes the update to its importers, which can end in a reload, and an accepted module inside an import cycle reloads if its update fails. `vite --debug hmr` logs the propagation and any cycle; the `vite:beforeFullReload` event fires in the page just before.

go deeper

for a junior

Recall the plain reasons: nothing accepted the update, index.html changed, or the config or an env file changed and the server restarted.

for a middle

Explain how Vite looks for an accepting module from the edited file to the entry, why a helper imported by main.ts reloads the page, and how to read the terminal lines.

for a senior

Diagnose reload storms with vite --debug hmr, the vite:beforeFullReload event and the importer chain, and separate cycles, invalidations and restarts from missing boundaries.

for a principal

Judge how much module structure a large app should bend to keep hot updates working, against the cost of occasional reloads and the clarity of a thin entry point.

## Hot update or reload: the decision Vite makes When a watched file changes, Vite's dev server either sends the browser a **hot update** (re-import a few modules, keep the page) or a **full reload** (throw the page away). The general model behind that choice — walking up the importers until a module agrees to take the update, and falling back to a reload when none does — is the subject of the general hot-reload material. This answer is about **Vite's own reasons** and how to see which one fired. In Vite, a module "agrees" by calling `import.meta.hot.accept` (directly, or through a framework plugin that injects the call into components). Such a module is an **HMR boundary**. ## Vite's reasons for a full reload | Trigger | What Vite does | What you see | |---|---|---| | No boundary between the edited file and a module with no importers | sends `full-reload` | terminal: `page reload src/…` | | `index.html` edited | sends `full-reload`; the template cannot be hot-updated | terminal: `page reload index.html` | | `vite.config.*`, a file it imports, or the mode's `.env` files edited | restarts the dev server | terminal: `… changed, restarting server...`; browser: `server connection lost. Polling for restart...`, then a reload | | a module calls `import.meta.hot.invalidate()` | treats it as not accepting and walks on to its importers | the module's message in both consoles, then an update or a reload | | an accepted module inside an **import cycle** whose re-import fails | the client reloads to reset execution order | browser: a `[hmr] … circular import` notice | | the page opened with the error overlay already showing | the first update reloads instead | a reload on the first save after the error | A seventh cause, a dependency discovered late that forces the dependency optimizer to run again, belongs with the pre-bundling material; it shows up as its own log line and reload. ## The common case: a module nobody accepts Framework plugins make **components** boundaries, so editing a component swaps it in place. A plain module is different. A `units.ts` with formatting helpers, imported by `main.ts` and by several components, has no `accept` of its own; if any chain of importers from it reaches `main.ts` without passing a boundary, the walk hits a module with no importers and the whole page reloads. That is why "every save reloads" usually means the edited file is imported somewhere **outside** the component tree — often directly by the entry. ## Edits that do not reload the page Some saves end without a full reload, and a few without any browser action at all, which is easy to confuse with a broken setup: - **CSS** imported from JavaScript is swapped without re-running scripts. - A file the current page never loaded, or that is not in the module graph, has nothing to update. - A module imported **only by server-rendering code** does not reload the browser by default. - Files under `node_modules` are not watched. - An import written with the **wrong letter case** (`./Units.ts` for `units.ts`) can make Vite detect the change but fail to hot-update it. ## Finding which cause fired 1. **Read the terminal line.** `hmr update …` is a hot update; `page reload <file>` is a reload (with a reason in parentheses for some causes, such as a circular `invalidate`); `changed, restarting server...` is a restart. 2. **Run `vite --debug hmr`.** It logs how the update propagated and prints the import path of any cycle involved. 3. **Watch the browser console.** Vite's client logs `[vite]` messages for lost connections, invalidations and failed updates. 4. **Listen for the event.** `import.meta.hot.on('vite:beforeFullReload', …)` runs just before a reload, which helps when something must be saved or logged first. 5. **Trace the importers** of the logged file and ask which of them accepts. ## Turning reloads into updates - Keep the entry thin: let it mount the app, and keep shared helpers out of it. - Give long-lived plain modules (a chart, a socket client) their own `accept` and `dispose`. - Break import cycles that pass through a boundary. - Accept that a config or `.env` change restarts the server; that reload is deliberate. - Re-check after each change with `vite --debug hmr`: the log should end at a boundary rather than at the entry.

  • Editing .env.development reloads the page and leaves no hmr line in the terminal; why is that expected?
    Vite treats the mode's `.env` files like its config file: a change restarts the dev server so the new values are loaded, and the terminal says the file changed and the server is restarting. The browser loses its socket, polls until the server answers, then reloads. No hot update is attempted.
  • A self-accepting module calls import.meta.hot.invalidate() in its accept callback; when does that still end in a full reload?
    `invalidate()` makes Vite treat the module as if it did not accept and continue to its importers. If one of them accepts the module as a dependency, that importer takes the update. If the walk reaches a module with no importers, the page reloads; and if the update would be accepted again through the module that first invalidated it, Vite reloads and logs a circular invalidation.
  • How can code in the page run something just before Vite reloads it?
    Register `import.meta.hot.on('vite:beforeFullReload', cb)` inside an `if (import.meta.hot)` guard. Vite dispatches the event before a full reload, so the callback can log the reason or save transient state; it does not cancel the reload.

  • Every saved file is hot-swapped, so a reload means HMR is broken
  • Editing index.html is hot-updated like any module
  • A vite.config.ts change needs a manual restart to apply
  • A syntax error in the edited file is answered with a page reload
  • Any import cycle in the app forces a reload on every save
open as a page

In Vite 8, how do import.meta.hot.accept, dispose and data let a charting module keep its zoom level across edits?

level: middleimportance: must knowfreq 14%

basics

~10 s

The module self-accepts with import.meta.hot.accept(), its dispose callback writes the zoom into data and destroys the old chart, and the new instance reads import.meta.hot.data.zoom. All of it sits inside if (import.meta.hot).

open as a page

Inside a dev container, Vite's dev server reports port 5174 and the host's browser cannot reach it; which server options explain that?

level: juniorimportance: should knowfreq 12%

basics

~10 s

Vite's dev server defaults to port 5173, quietly takes the next free port when that one is busy, and listens on localhost only. In a container, set server.host to true and server.strictPort to true.

open as a page

In Vite's dev server, how do you configure server.proxy so /api calls and a websocket feed reach a backend on port 8080?

level: middleimportance: should knowfreq 16%

basics

~20 s

Add server.proxy entries keyed by path prefix: '/api' with target http://localhost:8080, changeOrigin and a rewrite that strips the prefix, and '/feed' with a ws:// target and ws: true. The browser stays same-origin, so no CORS.

open as a page

Vite's dev server answers 403 for files from a shared packages/maps folder outside the project root; why, and how do you allow them safely?

level: seniorimportance: should knowfreq 7%

basics

~20 s

server.fs.strict is on by default, so Vite serves only files inside server.fs.allow, which defaults to the detected workspace root or else the project root. Add packages/maps to the list, keep searchForWorkspaceRoot, and never turn strict off.

open as a page

In Vite 8.1 and later, a dev server reached through an HTTPS reverse proxy serves pages but never hot-updates; how does server.ws fix the HMR socket?

level: seniorimportance: nice to knowfreq 4%

basics

~20 s

Vite's HMR client opens a WebSocket to the page's own host and port, so a proxy that does not forward WebSocket upgrades breaks it. Proxy WebSockets too, or set server.ws options such as clientPort, which Vite 8.1 moved from server.hmr.

open as a page