feat: rename server.hmr options to server.ws options (#21357)

Co-authored-by: Bjorn Lu <bjornlu.dev@gmail.com>

Author: sapphi-red

docs/config/server-options.md

@@ -181,17 +181,45 @@ Specify server response headers.
 
 ## server.hmr
 
-- **Type:** `boolean | { protocol?: string, host?: string, port?: number, path?: string, timeout?: number, overlay?: boolean, clientPort?: number, server?: Server }`
+- **Type:** `boolean | { overlay?: boolean }`
 
-Disable or configure HMR connection (in cases where the HMR websocket must use a different address from the http server).
+Disable or configure HMR behavior.
 
 Set `server.hmr.overlay` to `false` to disable the server error overlay.
 
-`protocol` sets the WebSocket protocol used for the HMR connection: `ws` (WebSocket) or `wss` (WebSocket Secure).
+::: warning Deprecated Options
 
-`clientPort` is an advanced option that overrides the port only on the client side, allowing you to serve the websocket on a different port than the client code looks for it on.
+The WebSocket-related options (`protocol`, `host`, `port`, `path`, `clientPort`, `timeout`, `server`) are deprecated. Use [`server.ws`](#server-ws) instead. These options are automatically synced, so existing configurations will continue to work.
 
-When `server.hmr.server` is defined, Vite will process the HMR connection requests through the provided server. If not in middleware mode, Vite will attempt to process HMR connection requests through the existing server. This can be helpful when using self-signed certificates or when you want to expose Vite over a network on a single port.
+:::
+
+## server.ws
+
+- **Type:** `false | { protocol?: string, host?: string, port?: number, path?: string, timeout?: number, clientPort?: number, server?: Server }`
+
+Configure WebSocket connection options. Set to `false` to disable the WebSocket connection entirely.
+
+- `protocol` - WebSocket protocol (`ws` or `wss`)
+- `host` - WebSocket server host
+- `port` - WebSocket server port
+- `path` - WebSocket path
+- `clientPort` - Override the port on the client side, allowing you to serve the websocket on a different port than the client code looks for it on
+- `timeout` - Connection timeout in milliseconds (default: 30000)
+- `server` - Use a custom HTTP server for WebSocket connections
+
+When `server.ws.server` is defined, Vite will process the WebSocket connection requests through the provided server. If not in middleware mode, Vite will attempt to process WebSocket connection requests through the existing server. This can be helpful when using self-signed certificates or when you want to expose Vite over a network on a single port.
+
+```js
+export default defineConfig({
+  server: {
+    ws: {
+      protocol: 'wss',
+      host: 'localhost',
+      port: 3001,
+    },
+  },
+})
+```
 
 Check out [`vite-setup-catalogue`](https://github.com/sapphi-red/vite-setup-catalogue) for some examples.
 
@@ -200,14 +228,14 @@ Check out [`vite-setup-catalogue`](https://github.com/sapphi-red/vite-setup-cata
 With the default configuration, reverse proxies in front of Vite are expected to support proxying WebSocket. If the Vite HMR client fails to connect WebSocket, the client will fall back to connecting the WebSocket directly to the Vite HMR server bypassing the reverse proxies:
 
 ```
-Direct websocket connection fallback. Check out https://vite.dev/config/server-options.html#server-hmr to remove the previous connection error.
+Direct websocket connection fallback. Check out https://vite.dev/config/server-options.html#server-ws to remove the previous connection error.
 ```
 
 The error that appears in the Browser when the fallback happens can be ignored. To avoid the error by directly bypassing reverse proxies, you could either:
 
 - configure the reverse proxy to proxy WebSocket too
-- set [`server.strictPort = true`](#server-strictport) and set `server.hmr.clientPort` to the same value with `server.port`
-- set `server.hmr.port` to a different value from [`server.port`](#server-port)
+- set [`server.strictPort = true`](#server-strictport) and set `server.ws.clientPort` to the same value with `server.port`
+- set `server.ws.port` to a different value from [`server.port`](#server-port)
 
 :::
 

packages/vite/src/node/__tests__/config.spec.ts

@@ -2,7 +2,7 @@ import http from 'node:http'
 import os from 'node:os'
 import path from 'node:path'
 import fs from 'node:fs'
-import { afterEach, describe, expect, test, vi } from 'vitest'
+import { afterEach, assert, describe, expect, test, vi } from 'vitest'
 import type { InlineConfig, PluginOption } from '..'
 import type { UserConfig, UserConfigExport } from '../config'
 import { defineConfig, loadConfigFromFile, resolveConfig } from '../config'
@@ -293,7 +293,11 @@ describe('mergeConfig', () => {
     }
 
     const mergedConfig = {
-      server: { allowedHosts: true },
+      server: {
+        allowedHosts: true,
+        hmr: expect.any(Object),
+        ws: expect.any(Object),
+      },
     }
 
     expect(mergeConfig(baseConfig, newConfig)).toEqual(mergedConfig)
@@ -665,6 +669,114 @@ describe('mergeConfig', () => {
     ).toBe('browser')
   })
 
+  test('syncs `server.hmr.*` to `server.ws.*`', () => {
+    const baseConfig = defineConfig({
+      server: {
+        hmr: {
+          protocol: 'wss',
+          host: 'example.com',
+          port: 3001,
+          clientPort: 443,
+          path: '/ws',
+          timeout: 60000,
+        },
+      },
+    })
+
+    const mergedConfig = mergeConfig(
+      {
+        server: { ws: {} },
+      },
+      baseConfig,
+    )
+
+    expect(mergedConfig.server.ws).toStrictEqual({
+      protocol: 'wss',
+      host: 'example.com',
+      port: 3001,
+      clientPort: 443,
+      path: '/ws',
+      timeout: 60000,
+    })
+    expect(mergedConfig.server.hmr).toStrictEqual({
+      protocol: 'wss',
+      host: 'example.com',
+      port: 3001,
+      clientPort: 443,
+      path: '/ws',
+      timeout: 60000,
+      server: undefined,
+    })
+  })
+
+  test('mergeConfig works with `server.ws` and `server.hmr`', () => {
+    const baseConfig = defineConfig({
+      server: {
+        ws: {
+          host: 'old-host.com',
+          port: 3001,
+        },
+      },
+    })
+
+    const newConfig = defineConfig({
+      server: {
+        hmr: {
+          host: 'new-host.com',
+          port: 3002,
+        },
+      },
+    })
+
+    const mergedConfig = mergeConfig(baseConfig, newConfig)
+
+    expect(mergedConfig.server.ws.host).toBe('new-host.com')
+    expect(mergedConfig.server.hmr.host).toBe('new-host.com')
+    expect(mergedConfig.server.ws.port).toBe(3002)
+    expect(mergedConfig.server.hmr.port).toBe(3002)
+  })
+
+  test('`server.hmr.overlay` is not mapped to `server.ws.overlay`', () => {
+    const config = mergeConfig(
+      {},
+      defineConfig({
+        server: {
+          hmr: {
+            overlay: false,
+          },
+        },
+      }),
+    )
+
+    expect(config.server.hmr.overlay).toBe(false)
+    // overlay should not be synced to ws
+    expect(config.server.ws?.overlay).toBeUndefined()
+  })
+
+  test('resolveConfig properly syncs hmr and ws', async () => {
+    const config = await resolveConfig(
+      {
+        server: {
+          hmr: {
+            host: 'test-host.com',
+            port: 4000,
+          },
+        },
+      },
+      'serve',
+    )
+
+    assert(typeof config.server.ws === 'object')
+    expect(config.server.ws.host).toBe('test-host.com')
+    expect(config.server.ws.port).toBe(4000)
+
+    assert(typeof config.server.hmr === 'object')
+    config.server.hmr!.host = 'new-host.com'
+
+    expect(config.server.ws.host).toBe('new-host.com')
+    expect(config.server.hmr.host).toBe('new-host.com')
+  })
+
   describe('later plugin can read `rollupOptions` set via `rolldownOptions` in earlier plugin', () => {
     test('top-level config', async () => {
       expect.assertions(2)

packages/vite/src/node/index.ts

@@ -231,6 +231,7 @@ export type {
 } from './server/transformRequest'
 export type {
   HmrOptions,
+  WsOptions,
   HmrContext,
   HotUpdateOptions,
   HotChannelListener,

packages/vite/src/node/plugins/clientInjections.ts

@@ -78,29 +78,30 @@ async function createClientConfigValueReplacer(
 
   const serverHost = `${resolvedServerHostname}:${resolvedServerPort}${devBase}`
 
-  let hmrConfig = config.server.hmr
-  hmrConfig = isObject(hmrConfig) ? hmrConfig : undefined
-  const host = hmrConfig?.host || null
-  const protocol = hmrConfig?.protocol || null
-  const timeout = hmrConfig?.timeout || 30000
-  const overlay = hmrConfig?.overlay !== false
-  const isHmrServerSpecified = !!hmrConfig?.server
+  const wsConfig = isObject(config.server.ws) ? config.server.ws : undefined
+  const host = wsConfig?.host || null
+  const protocol = wsConfig?.protocol || null
+  const timeout = wsConfig?.timeout || 30000
+  const isWsServerSpecified = !!wsConfig?.server
   const hmrConfigName = path.basename(config.configFile || 'vite.config.js')
 
-  // hmr.clientPort -> hmr.port
-  // -> (24678 if middleware mode and HMR server is not specified) -> new URL(import.meta.url).port
-  let port = hmrConfig?.clientPort || hmrConfig?.port || null
-  if (config.server.middlewareMode && !isHmrServerSpecified) {
+  const hmrConfig = isObject(config.server.hmr) ? config.server.hmr : undefined
+  const overlay = hmrConfig?.overlay !== false
+
+  // ws.clientPort -> ws.port
+  // -> (24678 if middleware mode and WS server is not specified) -> new URL(import.meta.url).port
+  let port = wsConfig?.clientPort || wsConfig?.port || null
+  if (config.server.middlewareMode && !isWsServerSpecified) {
     port ||= 24678
   }
 
-  let directTarget = hmrConfig?.host || resolvedServerHostname
-  directTarget += `:${hmrConfig?.port || resolvedServerPort}`
+  let directTarget = wsConfig?.host || resolvedServerHostname
+  directTarget += `:${wsConfig?.port || resolvedServerPort}`
   directTarget += devBase
 
   let hmrBase = devBase
-  if (hmrConfig?.path) {
-    hmrBase = path.posix.join(hmrBase, hmrConfig.path)
+  if (wsConfig?.path) {
+    hmrBase = path.posix.join(hmrBase, wsConfig.path)
   }
 
   const modeReplacement = escapeReplacement(config.mode)

packages/vite/src/node/server/hmr.ts

@@ -45,14 +45,45 @@ const whitespaceRE = /\s/
 
 const normalizedClientDir = normalizePath(CLIENT_DIR)
 
+export interface WsOptions {
+  protocol?: string
+  host?: string
+  port?: number
+  clientPort?: number
+  path?: string
+  timeout?: number
+  server?: HttpServer
+}
+
 export interface HmrOptions {
+  /**
+   * @deprecated Use `server.ws.protocol` instead.
+   */
   protocol?: string
+  /**
+   * @deprecated Use `server.ws.host` instead.
+   */
   host?: string
+  /**
+   * @deprecated Use `server.ws.port` instead.
+   */
   port?: number
+  /**
+   * @deprecated Use `server.ws.clientPort` instead.
+   */
   clientPort?: number
+  /**
+   * @deprecated Use `server.ws.path` instead.
+   */
   path?: string
+  /**
+   * @deprecated Use `server.ws.timeout` instead.
+   */
   timeout?: number
   overlay?: boolean
+  /**
+   * @deprecated Use `server.ws.server` instead.
+   */
   server?: HttpServer
 }
 

packages/vite/src/node/server/index.ts

@@ -42,6 +42,7 @@ import {
   normalizePath,
   resolveHostname,
   resolveServerUrls,
+  setupHmrWsOptionCompat,
   setupSIGTERMListener,
   teardownSIGTERMListener,
 } from '../utils'
@@ -98,7 +99,7 @@ import { ModuleGraph } from './mixedModuleGraph'
 import type { ModuleNode } from './mixedModuleGraph'
 import { notFoundMiddleware } from './middlewares/notFound'
 import { errorMiddleware } from './middlewares/error'
-import type { HmrOptions, NormalizedHotChannel } from './hmr'
+import type { HmrOptions, NormalizedHotChannel, WsOptions } from './hmr'
 import { handleHMRUpdate, updateModules } from './hmr'
 import { openBrowser as _openBrowser } from './openBrowser'
 import type { TransformOptions, TransformResult } from './transformRequest'
@@ -117,10 +118,10 @@ export interface ServerOptions extends CommonServerOptions {
    */
   hmr?: HmrOptions | boolean
   /**
-   * Do not start the websocket connection.
-   * @experimental
+   * Configure WebSocket connection options.
+   * Set to `false` to disable the WebSocket server and connection.
    */
-  ws?: false
+  ws?: WsOptions | false
   /**
    * Warm-up files to transform and cache the results in advance. This improves the
    * initial page load during server starts and prevents transform waterfalls.
@@ -1204,6 +1205,8 @@ export async function resolveServerOptions(
     raw ?? {},
   )
 
+  setupHmrWsOptionCompat(_server)
+
   const server: ResolvedServerOptions = {
     ..._server,
     fs: {

packages/vite/src/node/server/middlewares/__tests__/hostCheck.spec.ts

@@ -5,7 +5,7 @@ test('getAdditionalAllowedHosts', async () => {
   const actual = getAdditionalAllowedHosts(
     {
       host: 'vite.host.example.com',
-      hmr: {
+      ws: {
         host: 'vite.hmr-host.example.com',
       },
       origin: 'http://vite.origin.example.com:5173',

packages/vite/src/node/server/middlewares/hostCheck.ts

@@ -3,7 +3,7 @@ import type { Connect } from '#dep-types/connect'
 import type { ResolvedPreviewOptions, ResolvedServerOptions } from '../..'
 
 export function getAdditionalAllowedHosts(
-  resolvedServerOptions: Pick<ResolvedServerOptions, 'host' | 'hmr' | 'origin'>,
+  resolvedServerOptions: Pick<ResolvedServerOptions, 'host' | 'ws' | 'origin'>,
   resolvedPreviewOptions: Pick<ResolvedPreviewOptions, 'host'>,
 ): string[] {
   const list = []
@@ -17,10 +17,10 @@ export function getAdditionalAllowedHosts(
     list.push(resolvedServerOptions.host)
   }
   if (
-    typeof resolvedServerOptions.hmr === 'object' &&
-    resolvedServerOptions.hmr.host
+    typeof resolvedServerOptions.ws === 'object' &&
+    resolvedServerOptions.ws.host
   ) {
-    list.push(resolvedServerOptions.hmr.host)
+    list.push(resolvedServerOptions.ws.host)
   }
   if (
     typeof resolvedPreviewOptions.host === 'string' &&