From 9c0338375daacf98a3dad9b7d7a8cfbce7960ba6 Mon Sep 17 00:00:00 2001 From: neverland Date: Sun, 11 May 2025 10:11:47 +0800 Subject: [PATCH] docs: update dev server API documentation --- .../en/api/javascript-api/dev-server-api.mdx | 141 +++++++++++------- .../docs/en/config/dev/setup-middlewares.mdx | 34 ++--- .../zh/api/javascript-api/dev-server-api.mdx | 137 ++++++++++------- .../docs/zh/config/dev/setup-middlewares.mdx | 34 ++--- 4 files changed, 196 insertions(+), 150 deletions(-) diff --git a/website/docs/en/api/javascript-api/dev-server-api.mdx b/website/docs/en/api/javascript-api/dev-server-api.mdx index b059f14b5f..b1529be3f7 100644 --- a/website/docs/en/api/javascript-api/dev-server-api.mdx +++ b/website/docs/en/api/javascript-api/dev-server-api.mdx @@ -24,7 +24,51 @@ const server = await rsbuild.createDevServer(); console.log('the server is ', server); ``` -## API interface +## Example + +### Integrate with custom server + +Here is an example of integrating [express](https://expressjs.com/) with Rsbuild dev server: + +```ts +import { createRsbuild } from '@rsbuild/core'; +import express from 'express'; + +async function startDevServer() { + // Init Rsbuild + const rsbuild = await createRsbuild({ + rsbuildConfig: { + server: { + middlewareMode: true, + }, + }, + }); + const app = express(); + + // Create Rsbuild dev server instance + const rsbuildServer = await rsbuild.createDevServer(); + + // Apply Rsbuild's built-in middleware + app.use(rsbuildServer.middlewares); + + const server = app.listen(rsbuildServer.port, async () => { + // Notify Rsbuild that the custom server has started + await rsbuildServer.afterListen(); + }); + + rsbuildServer.connectWebSocket({ server }); +} +``` + +For detailed usage, please refer to: + +- [Example code](https://github.com/rspack-contrib/rstack-examples/blob/main/rsbuild/express/server.mjs). +- [rsbuild.createDevServer](/api/javascript-api/instance#rsbuildcreatedevserver) +- [server.middlewareMode](/config/server/middleware-mode) + +## API + +### Type definitions ```ts type EnvironmentAPI = { @@ -88,10 +132,12 @@ type RsbuildDevServer = { */ afterListen: () => Promise; /** - * Activate socket connection. + * Activates the WebSocket connection. * This ensures that HMR works properly. */ - connectWebSocket: (options: { server: HTTPServer }) => void; + connectWebSocket: (options: { + server: import('node:http').Server | import('node:http2').Http2SecureServer; + }) => void; /** * Close the Rsbuild server. */ @@ -134,81 +180,62 @@ function CreateDevServer( ): Promise; ``` -### sockWrite - -- **Type:** `(type: 'static-changed') => void` - -Sends some message to HMR client, and then the HMR client will take different actions depending on the message type. +### connectWebSocket -For example, if you send a `'static-changed'` message, the page will reload. +- **Type:** ```ts -const rsbuildServer = await rsbuild.createDevServer(); -if (someCondition) { - rsbuildServer.sockWrite('static-changed'); -} +type ConnectWebSocket = (options: { + server: import('node:http').Server | import('node:http2').Http2SecureServer; +}) => void; ``` -> Sending `content-changed` and `static-changed` have the same effect. Since `content-changed` has been deprecated, please use `static-changed` instead. - -## Example +Activates the WebSocket connection. This ensures that HMR works properly. -### Integrate with custom server +Rsbuild has a builtin WebSocket handler to support HMR: -Here is an example of integrating [express](https://expressjs.com/) with Rsbuild dev server: +1. When a user accesses a page through browser, a WebSocket connection request is automatically initiated to the server. +2. After the Rsbuild dev server detects the connection request, it instructs the builtin WebSocket handler to process it. +3. After the browser successfully establishes a connection with the Rsbuild WebSocket handler, real-time communication is possible. +4. The Rsbuild WebSocket handler notifies the browser after each recompilation is complete. The browser then sends a `hot-update.(js|json)` request to the dev server to load the new compiled module. -```ts -import { createRsbuild } from '@rsbuild/core'; -import express from 'express'; +When you use custom server, you may encounter HMR connection error problems. This is because the custom server does not forward WebSocket connection requests to Rsbuild's WebSocket handler. -async function startDevServer() { - // Init Rsbuild - const rsbuild = await createRsbuild({ - rsbuildConfig: { - server: { - middlewareMode: true, - }, - }, - }); - const app = express(); +At this time, you need to use the `connectWebSocket` method to enable Rsbuild to sense and process the WebSocket connection request from the browser. - // Create Rsbuild dev server instance - const rsbuildServer = await rsbuild.createDevServer(); +```ts +const rsbuildServer = await rsbuild.createDevServer(); +const httpServer = app.listen(rsbuildServer.port); - // Apply Rsbuild's built-in middleware - app.use(rsbuildServer.middlewares); +rsbuildServer.connectWebSocket({ server: httpServer }); +``` - const server = app.listen(rsbuildServer.port, async () => { - // Notify Rsbuild that the custom server has started - await rsbuildServer.afterListen(); - }); +### environments - rsbuildServer.connectWebSocket({ server }); -} -``` +- **Type:** [EnvironmentAPI](/api/javascript-api/environment-api#environment-api) -For detailed usage, please refer to: +Provides Rsbuild's [environment API](/api/javascript-api/environment-api#environment-api), which allows you to get the build outputs information for a specific environment in the server side. -- [Example code](https://github.com/rspack-contrib/rstack-examples/blob/main/rsbuild/express/server.mjs). -- [rsbuild.createDevServer](/api/javascript-api/instance#rsbuildcreatedevserver) -- [server.middlewareMode](/config/server/middleware-mode) +```ts title="rsbuild.config.ts" +const rsbuildServer = await rsbuild.createDevServer(); +const webStats = await rsbuildServer.environments.web.getStats(); -### connectWebSocket +console.log(webStats.toJson({ all: false })); +``` -Rsbuild has a builtin WebSocket handler to support HMR: +### sockWrite -1. When a user accesses a page through browser, a WebSocket connection request is automatically initiated to the server. -2. After the Rsbuild dev server detects the connection request, it instructs the builtin WebSocket handler to process it. -3. After the browser successfully establishes a connection with the Rsbuild WebSocket handler, real-time communication is possible. -4. The Rsbuild WebSocket handler notifies the browser after each recompilation is complete. The browser then sends a `hot-update.(js|json)` request to the dev server to load the new compiled module. +- **Type:** `(type: 'static-changed') => void` -When you use custom server, you may encounter HMR connection error problems. This is because the custom server does not forward WebSocket connection requests to Rsbuild's WebSocket handler. +Sends some message to HMR client, and then the HMR client will take different actions depending on the message type. -At this time, you need to use the `connectWebSocket` method to enable Rsbuild to sense and process the WebSocket connection request from the browser. +For example, if you send a `'static-changed'` message, the page will reload. ```ts const rsbuildServer = await rsbuild.createDevServer(); -const httpServer = app.listen(rsbuildServer.port); - -rsbuildServer.connectWebSocket({ server: httpServer }); +if (someCondition) { + rsbuildServer.sockWrite('static-changed'); +} ``` + +> Sending `content-changed` and `static-changed` have the same effect. Since `content-changed` has been deprecated, please use `static-changed` instead. diff --git a/website/docs/en/config/dev/setup-middlewares.mdx b/website/docs/en/config/dev/setup-middlewares.mdx index bcb45e635e..f50bb8dd28 100644 --- a/website/docs/en/config/dev/setup-middlewares.mdx +++ b/website/docs/en/config/dev/setup-middlewares.mdx @@ -56,44 +56,40 @@ export default { In the `setupMiddlewares` function, you can access the `server` object, which provides some server APIs. -### sockWrite +### environments -Sends some message to HMR client, see [Dev server API - sockWrite](/api/javascript-api/dev-server-api#sockwrite) for more details. - -For example, if you send a `'static-changed'` message, the page will reload. +Provides Rsbuild's [environment API](/api/javascript-api/environment-api#environment-api), see [Dev server API - environments](/api/javascript-api/dev-server-api#environments) for more details. ```ts title="rsbuild.config.ts" export default { dev: { setupMiddlewares: [ - (middlewares, server) => { - if (someCondition) { - server.sockWrite('static-changed'); - } + (middlewares, { environments }) => { + middlewares.unshift(async (req, _res, next) => { + const webStats = await environments.web.getStats(); + console.log(webStats.toJson({ all: false })); + next(); + }); }, ], }, }; ``` -### environments +### sockWrite -- **Type:** [EnvironmentAPI](/api/javascript-api/environment-api#environment-api) +Sends some message to HMR client, see [Dev server API - sockWrite](/api/javascript-api/dev-server-api#sockwrite) for more details. -`environments` includes Rsbuild's [environment API](/api/javascript-api/environment-api#environment-api), which allows you to get the build outputs information for a specific environment in the server side. +For example, if you send a `'static-changed'` message, the page will reload. ```ts title="rsbuild.config.ts" export default { dev: { setupMiddlewares: [ - (middlewares, server) => { - middlewares.unshift(async (req, _res, next) => { - const webStats = await server.environments.web.getStats(); - - console.log(webStats.toJson({ all: false })); - - next(); - }); + (middlewares, { sockWrite }) => { + if (someCondition) { + sockWrite('static-changed'); + } }, ], }, diff --git a/website/docs/zh/api/javascript-api/dev-server-api.mdx b/website/docs/zh/api/javascript-api/dev-server-api.mdx index f70a5268da..d06cd16ffb 100644 --- a/website/docs/zh/api/javascript-api/dev-server-api.mdx +++ b/website/docs/zh/api/javascript-api/dev-server-api.mdx @@ -24,7 +24,51 @@ const server = await rsbuild.createDevServer(); console.log('the server is ', server); ``` -## API 定义 +## 示例 + +### 与自定义 server 集成 + +下面是一个在 [express](https://expressjs.com/) 中集成 Rsbuild dev server 的例子: + +```ts +import { createRsbuild } from '@rsbuild/core'; +import express from 'express'; + +async function startDevServer() { + // 初始化 Rsbuild + const rsbuild = await createRsbuild({ + rsbuildConfig: { + server: { + middlewareMode: true, + }, + }, + }); + const app = express(); + + // 创建 Rsbuild dev server 实例 + const rsbuildServer = await rsbuild.createDevServer(); + + // 使用 Rsbuild 的内置中间件 + app.use(rsbuildServer.middlewares); + + const server = app.listen(rsbuildServer.port, async () => { + // 通知 Rsbuild 自定义 Server 已启动 + await rsbuildServer.afterListen(); + }); + + rsbuildServer.connectWebSocket({ server }); +} +``` + +更多用法可参考： + +- [示例代码](https://github.com/rspack-contrib/rstack-examples/blob/main/rsbuild/express/server.mjs)。 +- [rsbuild.createDevServer](/api/javascript-api/instance#rsbuildcreatedevserver) +- [server.middlewareMode](/config/server/middleware-mode) + +## API + +### 类型定义 ```ts type EnvironmentAPI = { @@ -88,10 +132,12 @@ type RsbuildDevServer = { */ afterListen: () => Promise; /** - * 激活 socket 连接 + * 激活 WebSocket 连接 * 这确保了 HMR 正常工作 */ - connectWebSocket: (options: { server: HTTPServer }) => void; + connectWebSocket: (options: { + server: import('node:http').Server | import('node:http2').Http2SecureServer; + }) => void; /** * 关闭 Rsbuild server */ @@ -133,79 +179,60 @@ function CreateDevServer( ): Promise; ``` -### sockWrite - -- **类型:** `(type: 'static-changed') => void` +### connectWebSocket -向 HMR 客户端传递一些消息，HMR 客户端将根据接收到的消息类型进行不同的处理。 - -例如，如果你发送一个 `'static-changed'` 的消息，页面将会重新加载。 +- **类型:** ```ts -const rsbuildServer = await rsbuild.createDevServer(); -if (someCondition) { - rsbuildServer.sockWrite('static-changed'); -} +type ConnectWebSocket = (options: { + server: import('node:http').Server | import('node:http2').Http2SecureServer; +}) => void; ``` -> 发送 `content-changed` 与 `static-changed` 具有相同的效果。由于 `content-changed` 已经被弃用，请优先使用 `static-changed`。 +激活 WebSocket 连接，这确保了 HMR 正常工作。 -## 示例 +Rsbuild 内置了 WebSocket 处理器以支持 HMR 功能： -### 与自定义 server 集成 +1. 当用户通过浏览器访问页面时，会自动向服务器发起 WebSocket 连接请求。 +2. Rsbuild 开发服务器检测到连接请求后，会指示内置的 WebSocket 处理器进行处理。 +3. 浏览器与 Rsbuild WebSocket 处理器成功建立连接后，便可进行实时通信。 +4. 每次重新编译完成后，Rsbuild WebSocket 处理器会通知浏览器。随后，浏览器向开发服务器发送 `hot-update.(js|json)` 请求，以加载编译后的新模块。 -下面是一个在 [express](https://expressjs.com/) 中集成 Rsbuild dev server 的例子: +当你使用自定义 server 时，可能会遇到 HMR 连接失败的问题。这是因为自定义 server 未能将 WebSocket 连接请求正确转发至 Rsbuild 的 WebSocket 处理器。此时，你需要调用 `connectWebSocket` 方法来让 Rsbuild 能够接收并处理来自浏览器的 WebSocket 连接请求。 ```ts -import { createRsbuild } from '@rsbuild/core'; -import express from 'express'; - -async function startDevServer() { - // 初始化 Rsbuild - const rsbuild = await createRsbuild({ - rsbuildConfig: { - server: { - middlewareMode: true, - }, - }, - }); - const app = express(); +const rsbuildServer = await rsbuild.createDevServer(); +const httpServer = app.listen(rsbuildServer.port); - // 创建 Rsbuild dev server 实例 - const rsbuildServer = await rsbuild.createDevServer(); +rsbuildServer.connectWebSocket({ server: httpServer }); +``` - // 使用 Rsbuild 的内置中间件 - app.use(rsbuildServer.middlewares); +### environments - const server = app.listen(rsbuildServer.port, async () => { - // 通知 Rsbuild 自定义 Server 已启动 - await rsbuildServer.afterListen(); - }); +- **Type:** [EnvironmentAPI](/api/javascript-api/environment-api#environment-api) - rsbuildServer.connectWebSocket({ server }); -} -``` +提供 Rsbuild 的 [environment API](/api/javascript-api/environment-api#environment-api)，这允许你在服务端获取特定环境下的构建产物信息。 -更多用法可参考： +```ts title="rsbuild.config.ts" +const rsbuildServer = await rsbuild.createDevServer(); +const webStats = await rsbuildServer.environments.web.getStats(); -- [示例代码](https://github.com/rspack-contrib/rstack-examples/blob/main/rsbuild/express/server.mjs)。 -- [rsbuild.createDevServer](/api/javascript-api/instance#rsbuildcreatedevserver) -- [server.middlewareMode](/config/server/middleware-mode) +console.log(webStats.toJson({ all: false })); +``` -### connectWebSocket +### sockWrite -Rsbuild 内置了 WebSocket 处理器以支持 HMR 功能： +- **类型:** `(type: 'static-changed') => void` -1. 当用户通过浏览器访问页面时，会自动向服务器发起 WebSocket 连接请求。 -2. Rsbuild 开发服务器检测到连接请求后，会指示内置的 WebSocket 处理器进行处理。 -3. 浏览器与 Rsbuild WebSocket 处理器成功建立连接后，便可进行实时通信。 -4. 每次重新编译完成后，Rsbuild WebSocket 处理器会通知浏览器。随后，浏览器向开发服务器发送 `hot-update.(js|json)` 请求，以加载编译后的新模块。 +向 HMR 客户端传递一些消息，HMR 客户端将根据接收到的消息类型进行不同的处理。 -当你使用自定义 server 时，可能会遇到 HMR 连接失败的问题。这是因为自定义 server 未能将 WebSocket 连接请求正确转发至 Rsbuild 的 WebSocket 处理器。此时，你需要调用 `connectWebSocket` 方法来让 Rsbuild 能够接收并处理来自浏览器的 WebSocket 连接请求。 +例如，如果你发送一个 `'static-changed'` 的消息，页面将会重新加载。 ```ts const rsbuildServer = await rsbuild.createDevServer(); -const httpServer = app.listen(rsbuildServer.port); - -rsbuildServer.connectWebSocket({ server: httpServer }); +if (someCondition) { + rsbuildServer.sockWrite('static-changed'); +} ``` + +> 发送 `content-changed` 与 `static-changed` 具有相同的效果。由于 `content-changed` 已经被弃用，请优先使用 `static-changed`。 diff --git a/website/docs/zh/config/dev/setup-middlewares.mdx b/website/docs/zh/config/dev/setup-middlewares.mdx index d41acb044e..2d04f1332c 100644 --- a/website/docs/zh/config/dev/setup-middlewares.mdx +++ b/website/docs/zh/config/dev/setup-middlewares.mdx @@ -56,44 +56,40 @@ export default { 在 `setupMiddlewares` 函数中，你可以访问到 `server` 对象，该对象提供了一些服务器 API。 -### sockWrite +### environments -向 HMR 客户端传递一些消息，详见 [Dev server API - sockWrite](/api/javascript-api/dev-server-api#sockwrite)。 - -例如，如果你发送一个 `'static-changed'` 的消息，页面将会重新加载。 +提供 Rsbuild 的 [environment API](/api/javascript-api/environment-api#environment-api)，详见 [Dev server API - environments](/api/javascript-api/dev-server-api#environments)。 ```ts title="rsbuild.config.ts" export default { dev: { setupMiddlewares: [ - (middlewares, server) => { - if (someCondition) { - server.sockWrite('static-changed'); - } + (middlewares, { environments }) => { + middlewares.unshift(async (req, _res, next) => { + const webStats = await environments.web.getStats(); + console.log(webStats.toJson({ all: false })); + next(); + }); }, ], }, }; ``` -### environments +### sockWrite -- **类型:** [EnvironmentAPI](/api/javascript-api/environment-api#environment-api) +向 HMR 客户端传递一些消息，详见 [Dev server API - sockWrite](/api/javascript-api/dev-server-api#sockwrite)。 -`environments` 包含 Rsbuild 的 [environment API](/api/javascript-api/environment-api#environment-api)，这允许你在服务端获取特定环境下的构建产物信息。 +例如，如果你发送一个 `'static-changed'` 的消息，页面将会重新加载。 ```ts title="rsbuild.config.ts" export default { dev: { setupMiddlewares: [ - (middlewares, server) => { - middlewares.unshift(async (req, _res, next) => { - const webStats = await server.environments.web.getStats(); - - console.log(webStats.toJson({ all: false })); - - next(); - }); + (middlewares, { sockWrite }) => { + if (someCondition) { + sockWrite('static-changed'); + } }, ], },