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 = {
  // The protocol name for the WebSocket request
  protocol?: 'ws' | 'wss';
  // The path for the WebSocket request
  path?: string;
  // The port number for the WebSocket request
  port?: string | number;
  // The host for the WebSocket request
  host?: string;
  // The maximum number of reconnection attempts after a WebSocket request is disconnected.
  reconnect?: number;
  // Whether to display an error overlay in the browser when a compilation error occurs
  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,
  reconnect: 100,
  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.

Error Overlay#

The dev.client.overlay option allows you to choose whether or not to enable the error overlay feature.

By default, Rsbuild will display an error overlay in the browser when a compilation error occurs, providing error messages and stacks:

If you need to disable the error overlay, you can set it to false:

export default {
  dev: {
    client: {
      overlay: false,
    },
  },
};