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?
answer
- a second connection besides the page
- inferred from the page's own address
- a direct fallback, then an error
- clientPort, port, protocol, path
- moved out of server.hmr in a minor
basics
~20 sVite'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.
solid answer
~50 sHot updates travel over a WebSocket that Vite's client opens separately from the page. By default it uses `wss` when the page is HTTPS and the page's own hostname and port, so behind a TLS-terminating proxy it connects to the proxy, and if the proxy does not forward upgrades the socket fails. Without an explicit port the client then tries Vite's server directly and logs `Direct websocket connection fallback.` when that works; behind TLS it usually fails too, and the console reports `failed to connect to websocket`. The documented fixes are to proxy WebSockets as well, to set `server.strictPort: true` with `server.ws.clientPort` equal to `server.port`, or to give `server.ws.port` its own value. Since Vite 8.1 these options (`protocol`, `host`, `port`, `path`, `clientPort`, `timeout`, `server`) live under `server.ws`; the `server.hmr` names are deprecated and synced, and `server.hmr.overlay` stays.
code
typescript · 16 lines// vite.config.ts
import { defineConfig } from 'vite'
export default defineConfig({
server: {
port: 5173,
strictPort: true,
// Vite 8.1+: WebSocket options live under server.ws
ws: {
clientPort: 5173, // the browser connects to Vite's port directly
},
hmr: {
overlay: true, // stays under server.hmr
},
},
})go deeper
Recall that hot updates arrive over a separate WebSocket, so a page can load while updates silently never come.
Explain how the client infers the socket's protocol, host and port from the page, and what the direct-connection fallback message means.
Pick among the documented fixes for a proxied or containerised setup, and know Vite 8.1 moved the socket options to server.ws while server.hmr.overlay stayed.
Standardise how a shared reverse proxy in front of dev servers handles WebSockets, so each team stops tuning socket options per project.
## Two connections, not one A page served by Vite's dev server talks to it over two channels: - **HTTP** for `index.html` and every module the browser imports; - a **WebSocket** opened by Vite's client script, over which the server pushes updates, reload requests and errors. A reverse proxy that forwards HTTP but not WebSocket upgrades gives exactly the symptom in the question: pages and modules load, and edits never arrive — no hot update and no reload, because the message that would trigger either has no way in. ## Where the client connects by default When nothing is configured, the client **infers** the socket address from the page: | Part | Default | |---|---| | protocol | `wss` if the page is HTTPS, otherwise `ws` | | host | the page's own hostname | | port | the page's own port | | path | Vite's `base` | | timeout | 30000 ms | Behind a TLS-terminating proxy at `https://dispatch.localhost:8443`, the client therefore opens `wss://dispatch.localhost:8443/…`, which only works if the proxy forwards the upgrade to Vite. ## What happens when it fails 1. The inferred connection fails. 2. If **no explicit port** is configured, the client falls back to connecting **directly** to the address the Vite server itself is on, using the same protocol as the page. 3. If that works, it logs `Direct websocket connection fallback.` and the earlier connection error can be ignored. 4. If it also fails, the console prints `[vite] failed to connect to websocket.` with a sketch of the HTTP path that works and the WebSocket path that does not. Behind TLS termination step 2 usually fails as well: the page demands `wss`, and Vite's own server is speaking plain HTTP. ## The fixes Vite documents 1. **Proxy WebSockets too.** Configure the reverse proxy to forward upgrade requests to Vite. This keeps every default and is the cleanest fix. 2. **Bypass the proxy on a fixed port.** Set `server.strictPort: true` and `server.ws.clientPort` to the same value as `server.port`, so the client connects straight to Vite's port. It only helps where the browser can reach that port with the protocol the page requires. 3. **Give the socket its own port.** Set `server.ws.port` to a value different from `server.port`, and Vite runs the WebSocket server there. Beyond those, `server.ws.protocol`, `host` and `path` override the inferred parts one by one, `timeout` changes the 30-second connection timeout, and `server.ws.server` hands Vite an HTTP server to process upgrades on, which helps with self-signed certificates or a single exposed port. ## Vite 8.1: from `server.hmr` to `server.ws` | Up to Vite 8.0 | Vite 8.1 and later | |---|---| | `server.hmr.protocol`, `host`, `port`, `path` | `server.ws.protocol`, `host`, `port`, `path` | | `server.hmr.clientPort`, `timeout`, `server` | `server.ws.clientPort`, `timeout`, `server` | | `server.hmr.overlay` | unchanged: `server.hmr.overlay` | - The `server.hmr` socket options are **deprecated, not removed**, and are **synced automatically**, so an older config keeps working while you rename. - `server.ws: false` disables the WebSocket connection entirely; `server.hmr: false` disables HMR. - Answers that say "set `server.hmr.clientPort`" describe Vite 8.0 and earlier. ## A worked setup The dispatch console runs Vite on port 5173 inside a dev container, and developers open it through a TLS-terminating reverse proxy at `https://dispatch.localhost:8443`. The page loads, so HTTP forwarding works. The client then opens `wss://dispatch.localhost:8443/`; the proxy answers it like an ordinary request instead of forwarding the upgrade, and the socket fails. The direct fallback tries `wss://` against Vite's plain-HTTP port and fails too. The fix that keeps every Vite default is in the proxy: forward requests carrying the `Upgrade: websocket` and `Connection: Upgrade` headers to the same upstream as the page. Only when the proxy cannot be changed do the `server.ws` options become the answer. ## Reading the symptoms - **Edits never arrive, console shows a failed socket**: the proxy is not forwarding upgrades. - **`Direct websocket connection fallback.`**: it works, bypassing the proxy; configure the proxy to silence it. - **`server connection lost. Polling for restart...`**: the socket dropped after working; the client reloads when the server answers again. - **No socket errors but still no updates**: the problem is elsewhere, in what the edited module accepts.
- An older config sets server.hmr.clientPort; does it still work in Vite 8.3, and what should you change?It still works: Vite 8.1 deprecated the `server.hmr` WebSocket options and syncs them to `server.ws` automatically. Rename it to `server.ws.clientPort` so the config matches current docs and survives the eventual removal, and leave `server.hmr.overlay` where it is.
- When is server.ws: false the right setting?When you deliberately want no live channel from the dev server to the page. It disables the WebSocket connection entirely, so the server can push no hot updates, no reload requests and no error overlay to the browser. It is a separate switch from `server.hmr: false`, which the docs describe as disabling HMR itself.
- The HMR socket always connects to localhost:5173 whatever the page's address
- A server.proxy rule with ws: true is what carries Vite's HMR messages
- In Vite 8.1 server.hmr.clientPort was removed and now throws
- server.hmr.overlay moved to server.ws.overlay in Vite 8.1
- If the HMR socket fails, Vite falls back to reloading on every save
Assumes Vite 8.1 or later; 8.1.0 moved the HMR WebSocket options from server.hmr to server.ws and kept the old names as deprecated, synced aliases.