Is it possible to disable both server.hmr and server.hmr.overlay?

[FrankFang]

When I set server.hmr to false, the server.hmr.overlay functionality is still enabled;
When I set server.hmr.overlay to false, the server.hmr functionality remains enabled;
It appears impossible to disable both.

[chrisjcthomas]

From the Vite config docs, these two switches control different things:

• server.hmr: false disables the HMR connection itself
• server.hmr.overlay: false disables the error overlay

So there isn't a separate third "disable both together" flag because those are already the two knobs.

If you're still seeing an overlay after setting server.hmr.overlay = false, my first guess would be that the overlay you're seeing is not the HMR error overlay controlled by that option.

So the intended config would be:

export default defineConfig({
  server: {
    hmr: false,
  },
})

or, if you still want HMR but not the overlay:

export default defineConfig({
  server: {
    hmr: {
      overlay: false,
    },
  },
})

If you can share what exact overlay/error is still appearing, that would help confirm whether it's coming from HMR or from a different dev-server path.

[everton-dgn]

Adding to @chrisjcthomas's answer: if you're still seeing an overlay after setting server.hmr.overlay: false, it almost certainly isn't Vite's.

The way the two flags relate, internally:

• server.hmr: false stops Vite from injecting the @vite/client script, which owns both the HMR WebSocket and the overlay. So both disappear in one setting.
• server.hmr: { overlay: false } keeps the WebSocket (so HMR still works) but suppresses the built-in overlay UI.

There's no third "disable both" option because the two above are already the two knobs.

What catches people out is that framework plugins ship their own overlays, wired to the same WebSocket but drawn independently. If you still see an overlay after turning Vite's off:

// @vitejs/plugin-vue
vue({ devToolsEnabled: false })

// @vitejs/plugin-react
react({ overlay: false })

Also worth checking for vite-plugin-checker or vite-plugin-inspect in your plugins array: both render their own overlay UIs on top of Vite.

So the configs you already have are the intended shapes:

// disable HMR and overlay together
export default defineConfig({
  server: { hmr: false },
})

// keep HMR, just lose the overlay
export default defineConfig({
  server: { hmr: { overlay: false } },
})

If an overlay still renders after server.hmr: false, sharing the overlay text / a screenshot would help narrow down which plugin is injecting it.

[DaCameraGirl]

Yes, it is possible — and server.hmr: false is actually the single switch that disables both.

The two options control different things, but server.hmr: false covers both:

• server.hmr: false — disables the entire HMR WebSocket connection. When HMR is off, Vite no longer injects the client script at all, which means the overlay has nothing to run on and is also disabled.
• server.hmr.overlay: false — only disables the error overlay UI while keeping the HMR connection alive.

So setting both feels redundant because they're not independent. The correct config to disable everything:

// vite.config.ts
export default defineConfig({
  server: {
    hmr: false,
  },
});

If an overlay still appears after server.hmr: false

It's not coming from Vite's core — it's being injected by a framework plugin. Common culprits:

React (@vitejs/plugin-react):

plugins: [
  react({
    // React's fast refresh has its own overlay behavior
  }),
],

React's fast refresh overlay is controlled independently. You may need to disable fast refresh entirely:

react({ fastRefresh: false })

vite-plugin-checker:

checker({
  overlay: false, // disable the checker's overlay specifically
})

The way to identify which plugin is injecting the overlay is to temporarily remove plugins one at a time until the overlay disappears, then configure that specific plugin's overlay option.

[athaillahbagas]

I checked this with Vite 8.3.6 in a minimal project. server.hmr: false still injects /@vite/client, and the served client still has enableOverlay = true. So the earlier claim that this setting removes the client script does not hold for that version.

For current Vite, you can disable the WebSocket connection and its error overlay separately:

import { defineConfig } from 'vite'

export default defineConfig({
  server: {
    ws: false,
    hmr: { overlay: false },
  },
})

In the same reproduction, this resolves to ws: false and serves enableOverlay = false. I have not verified this configuration against older Vite versions.

One distinction: Vite's HTML 500 error response has a separate overlay-rendering path. If the overlay appears on a failed initial document request, rather than after a WebSocket error, these settings may not cover that case. The requested URL, response status, and Vite version would help identify which path is involved.

References:

• WebSocket option
• Overlay injection, pinned version
• HTML error response

Reproduction and drafting were AI-assisted.