dev.client#

Configure the client code injected by Rsbuild during the development process. This can be used to set the WebSocket URL for HMR.

• Type:

type Client = {
  /** Specify the protocol name for the WebSocket request */
  protocol?: 'ws' | 'wss';
  /** Specify the path for the WebSocket request */
  path?: string;
  /** Specify the port number for the WebSocket request */
  port?: string | number;
  /** Specify the host for the WebSocket request */
  host?: string;
  /**
   * Shows overlay in the browser when there are compiler errors
   * This feature requires the current browser version to support [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)
   */
  overlay?: boolean;
};

• Default:

const defaultConfig = {
  path: '/rsbuild-hmr',
  // By default it is set to "location.port"
  port: '',
  // By default it is set to "location.hostname"
  host: '',
  // By default it is set to "location.protocol === 'https:' ? 'wss' : 'ws'""
  protocol: undefined,
  overlay: true,
};

Configure WebSocket URL#

By default, when you start the dev server and visit the http://localhost:3000/, a WebSocket request is made to ws://localhost:3000/rsbuild-hmr, establishing a connection between the page and the dev server.

In some development scenarios, you may need to adjust the WebSocket URL to ensure that the WebSocket request can connect correctly.

For example, if you are developing using a proxy tool, you may actually be accessing an online domain. In this case, you can manually configure dev.client to point the WebSocket URL to your local dev server. Below is an example where the WebSocket request URL is ws://127.0.0.1:3000/rsbuild-hmr:

export default {
  dev: {
    client: {
      protocol: 'ws',
      // Usually `127.0.0.1` is used to avoid cross-origin requests being blocked by the browser
      host: '127.0.0.1',
      port: 3000,
    },
  },
};

Port placeholder#

The port number that Rsbuild server listens on may change. For example, if the port is in use, Rsbuild will automatically increment the port number until it finds an available port.

To avoid client.port becoming invalid due to port changes, you can use one of the following methods:

• Enable server.strictPort.
• Use the <port> placeholder to refer to the current port number. Rsbuild will replace the placeholder with the actual port number it is listening on.

export default {
  dev: {
    client: {
      port: '<port>',
    },
  },
};

hot-update files#

During the HMR process, the page will make GET requests to get hot-update files, including *.hot-update.json and *.hot-update.js. These files contain the necessary information for hot updates, such as the updated modules and their code.

Hot-update files are considered to be static assets. If you need to configure the URL for hot-update files, please use the dev.assetPrefix option.