feat(core): support environment.hot.send API (#7475)

Author: chenjiahan

e2e/cases/javascript-api/environment-hot-send/index.test.ts

@@ -0,0 +1,62 @@
+import { expect, test } from '@e2e/helper';
+import { createRsbuild } from '@rsbuild/core';
+
+test('should send HMR messages to the matched environment only', async ({
+  page,
+  context,
+}) => {
+  const rsbuild = await createRsbuild({
+    cwd: import.meta.dirname,
+    config: {
+      environments: {
+        web: {},
+        web1: {
+          dev: {
+            assetPrefix: 'auto',
+          },
+          source: {
+            entry: {
+              main: './src/web1.ts',
+            },
+          },
+          output: {
+            distPath: {
+              root: 'dist/web1',
+              html: 'html1',
+            },
+          },
+        },
+      },
+    },
+  });
+
+  const server = await rsbuild.createDevServer();
+
+  await server.listen();
+  const web1Page = await context.newPage();
+
+  await page.goto(`http://localhost:${server.port}`);
+  await web1Page.goto(`http://localhost:${server.port}/web1/html1/main`);
+
+  await expect(page.locator('#title')).toHaveText('web');
+  await expect(web1Page.locator('#title')).toHaveText('web1');
+  await expect(page.locator('#count')).toHaveText('0');
+  await expect(web1Page.locator('#count')).toHaveText('0');
+
+  server.environments.web.hot.send('custom', {
+    event: 'count',
+  });
+
+  await expect(page.locator('#count')).toHaveText('1');
+  await expect(web1Page.locator('#count')).toHaveText('0');
+
+  server.environments.web1.hot.send('custom', {
+    event: 'count',
+  });
+
+  await expect(page.locator('#count')).toHaveText('1');
+  await expect(web1Page.locator('#count')).toHaveText('1');
+
+  await web1Page.close();
+  await server.close();
+});

e2e/cases/javascript-api/environment-hot-send/src/index.ts

@@ -0,0 +1,19 @@
+/// <reference types="@rsbuild/core/types" />
+
+const titleEl = document.createElement('div');
+titleEl.id = 'title';
+titleEl.innerText = 'web';
+
+const countEl = document.createElement('div');
+countEl.id = 'count';
+countEl.innerText = '0';
+
+document.body.append(titleEl, countEl);
+
+if (import.meta.webpackHot) {
+  import.meta.webpackHot.on('count', () => {
+    countEl.innerText = String(Number(countEl.innerText) + 1);
+  });
+
+  import.meta.webpackHot.accept();
+}

e2e/cases/javascript-api/environment-hot-send/src/web1.ts

@@ -0,0 +1,19 @@
+/// <reference types="@rsbuild/core/types" />
+
+const titleEl = document.createElement('div');
+titleEl.id = 'title';
+titleEl.innerText = 'web1';
+
+const countEl = document.createElement('div');
+countEl.id = 'count';
+countEl.innerText = '0';
+
+document.body.append(titleEl, countEl);
+
+if (import.meta.webpackHot) {
+  import.meta.webpackHot.on('count', () => {
+    countEl.innerText = String(Number(countEl.innerText) + 1);
+  });
+
+  import.meta.webpackHot.accept();
+}

packages/core/src/server/devServer.ts

@@ -55,7 +55,7 @@ type ExtractSocketMessageData<T extends ServerMessage['type']> =
     ? Extract<ServerMessage, { type: T }>['data']
     : undefined;
 
-export type SockWrite = <T extends ServerMessage['type']>(
+export type HotSend = <T extends ServerMessage['type']>(
   type: T,
   data?: ExtractSocketMessageData<T>,
 ) => void;
@@ -87,7 +87,7 @@ export type RsbuildDevServer = RsbuildServerBase & {
    * - `static-changed`: Alias of `full-reload` for backward compatibility.
    * - `custom`: Send custom messages via `custom` type with optional data to the browser and handle them via HMR events.
    */
-  sockWrite: SockWrite;
+  sockWrite: HotSend;
 };
 
 export async function createDevServer<
@@ -275,6 +275,16 @@ export async function createDevServer<
   );
 
   const environmentAPI: EnvironmentAPI = {};
+  const createHotSend =
+    (token?: string): HotSend =>
+    (type, data) =>
+      state.buildManager?.socketServer.sockWrite(
+        {
+          type,
+          data,
+        } as ServerMessage,
+        token,
+      );
 
   const getErrorMsg = (method: string) =>
     `${color.dim('[rsbuild:server]')} Can not call ` +
@@ -284,6 +294,9 @@ export async function createDevServer<
   context.environmentList.forEach((environment, index) => {
     environmentAPI[environment.name] = {
       context: environment,
+      hot: {
+        send: createHotSend(environment.webSocketToken),
+      },
       getStats: async () => {
         if (!state.buildManager) {
           throw new Error(getErrorMsg('getStats'));
@@ -326,11 +339,7 @@ export async function createDevServer<
         middlewares,
       });
 
-  const sockWrite: SockWrite = (type, data) =>
-    state.buildManager?.socketServer.sockWrite({
-      type,
-      data,
-    } as ServerMessage);
+  const sockWrite = createHotSend();
 
   const devServer: RsbuildDevServer = {
     port,

packages/core/src/types/config.ts

@@ -20,7 +20,7 @@ import type {
 } from 'http-proxy-middleware';
 import type { RspackChain } from 'rspack-chain';
 import type { FileDescriptor } from 'rspack-manifest-plugin';
-import type { RsbuildDevServer } from '../server/devServer';
+import type { HotSend, RsbuildDevServer } from '../server/devServer';
 import type { RsbuildPreviewServer } from '../server/previewServer';
 import type { Logger } from '../logger';
 import type {
@@ -1810,6 +1810,13 @@ export type EnvironmentAPI = Record<
      */
     getTransformedHtml: (entryName: string) => Promise<string>;
 
+    /**
+     * Send HMR message to the current environment only.
+     */
+    hot: {
+      send: HotSend;
+    };
+
     /**
      * Provides some context information about the current environment
      */

website/docs/en/api/javascript-api/environment-api.mdx

@@ -228,6 +228,9 @@ type EnvironmentAPI = {
     getStats: () => Promise<Stats>;
     loadBundle: <T = unknown>(entryName: string) => Promise<T>;
     getTransformedHtml: (entryName: string) => Promise<string>;
+    hot: {
+      send: SockWrite;
+    };
   };
 };
 ```
@@ -304,3 +307,28 @@ const html = await environments.web.getTransformedHtml('main');
 ```
 
 This method returns the complete HTML string, including all resources and content injected through HTML plugins.
+
+### hot.send
+
+Send an HMR message to the client of the current environment only.
+
+This works the same as [server.sockWrite](/api/javascript-api/server-api#sockwrite), but it only affects the matched environment.
+
+- **Type:**
+
+```ts
+type SockWrite = {
+  (type: 'full-reload', data?: { path?: string }): void;
+  (type: 'static-changed'): void;
+  (type: 'custom', data: { event: string; data?: any }): void;
+};
+```
+
+- **Example:**
+
+```ts
+environments.web.hot.send('custom', {
+  event: 'count',
+  data: { value: 1 },
+});
+```

website/docs/zh/api/javascript-api/environment-api.mdx

@@ -229,6 +229,9 @@ type EnvironmentAPI = {
     getStats: () => Promise<Stats>;
     loadBundle: <T = unknown>(entryName: string) => Promise<T>;
     getTransformedHtml: (entryName: string) => Promise<string>;
+    hot: {
+      send: SockWrite;
+    };
   };
 };
 ```
@@ -305,3 +308,28 @@ const html = await environments.web.getTransformedHtml('main');
 ```
 
 该方法会返回完整的 HTML 字符串，包含了所有通过 HTML 插件注入的资源和内容。
+
+### hot.send
+
+向当前 environment 对应的客户端发送 HMR 消息。
+
+它和 [server.sockWrite](/api/javascript-api/server-api#sockwrite) 的行为一致，区别是只会影响当前匹配的 environment。
+
+- **类型：**
+
+```ts
+type SockWrite = {
+  (type: 'full-reload', data?: { path?: string }): void;
+  (type: 'static-changed'): void;
+  (type: 'custom', data: { event: string; data?: any }): void;
+};
+```
+
+- **示例：**
+
+```ts
+environments.web.hot.send('custom', {
+  event: 'count',
+  data: { value: 1 },
+});
+```