web-infra-dev · chenjiahan · Feb 21, 2025 · Feb 21, 2025
diff --git a/website/docs/en/api/javascript-api/dev-server-api.mdx b/website/docs/en/api/javascript-api/dev-server-api.mdx
@@ -140,7 +140,13 @@ import express from 'express';
 
 async function startDevServer() {
   // Init Rsbuild
-  const rsbuild = await createRsbuild({});
+  const rsbuild = await createRsbuild({
+    rsbuildConfig: {
+      server: {
+        middlewareMode: true,
+      },
+    },
+  });
 
   const app = express();
 
@@ -159,7 +165,11 @@ async function startDevServer() {
 }
 ```
 
-For detailed usage, please refer to: [Example](https://github.com/rspack-contrib/rspack-examples/blob/main/rsbuild/express/server.mjs).
+For detailed usage, please refer to:
+
+- [Example code](https://github.com/rspack-contrib/rspack-examples/blob/main/rsbuild/express/server.mjs).
+- [rsbuild.createDevServer](/api/javascript-api/instance#rsbuildcreatedevserver)
+- [server.middlewareMode](/config/server/middleware-mode)
 
 ### connectWebSocket
 

diff --git a/website/docs/en/community/releases/v0-5.mdx b/website/docs/en/community/releases/v0-5.mdx
@@ -50,7 +50,13 @@ import { createRsbuild } from '@rsbuild/core';
 
 async function startCustomServer() {
   const app = express();
-  const rsbuild = await createRsbuild();
+  const rsbuild = await createRsbuild({
+    rsbuildConfig: {
+      server: {
+        middlewareMode: true,
+      },
+    },
+  });
   const { port, middlewares } = await rsbuild.createDevServer();
 
   app.use(middlewares);

diff --git a/website/docs/en/config/server/middleware-mode.mdx b/website/docs/en/config/server/middleware-mode.mdx
@@ -0,0 +1,39 @@
+# server.middlewareMode
+
+- **Type:** `boolean`
+- **Default:** `false`
+- **Version:** `>= 1.2.12`
+
+Whether to create Rsbuild's server in middleware mode, which is useful for integrating with other servers.
+
+When this option is enabled, Rsbuild will not create an HTTP server. This option is usually only needed when using the JavaScript API of Rsbuild.
+
+## Example
+
+A typical use case is that you want to integrate the Rsbuild server into a custom server. You can achieve this by combining `server.middlewareMode` and [rsbuild.createDevServer](/api/javascript-api/instance#rsbuildcreatedevserver).
+
+```ts
+import { createRsbuild } from '@rsbuild/core';
+import express from 'express';
+
+async function startDevServer() {
+  // Initialize Rsbuild in middleware mode
+  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 middlewares
+  app.use(rsbuildServer.middlewares);
+}
+```
+
+> See [Integrate with custom server](/api/javascript-api/dev-server-api#integrate-with-custom-server) for more details.
diff --git a/website/docs/en/guide/migration/vite.mdx b/website/docs/en/guide/migration/vite.mdx
@@ -137,6 +137,7 @@ Here is the corresponding Rsbuild configuration for Vite configuration:
 | server.proxy, preview.proxy           | [server.proxy](/config/server/proxy)                             |
 | server.headers, preview.headers       | [server.headers](/config/server/headers)                         |
 | server.hmr                            | [dev.hmr](/config/dev/hmr), [dev.client](/config/dev/client)     |
+| server.middlewareMode                 | [server.middlewareMode](/config/server/middleware-mode)          |
 | build.target, build.cssTarget         | [Browserslist](/guide/advanced/browserslist)                     |
 | build.outDir, build.assetsDir         | [output.distPath](/config/output/dist-path)                      |
 | build.assetsInlineLimit               | [output.dataUriLimit](/config/output/data-uri-limit)             |

diff --git a/website/docs/zh/api/javascript-api/dev-server-api.mdx b/website/docs/zh/api/javascript-api/dev-server-api.mdx
@@ -140,7 +140,13 @@ import express from 'express';
 
 async function startDevServer() {
   // 初始化 Rsbuild
-  const rsbuild = await createRsbuild({});
+  const rsbuild = await createRsbuild({
+    rsbuildConfig: {
+      server: {
+        middlewareMode: true,
+      },
+    },
+  });
 
   const app = express();
 
@@ -159,7 +165,11 @@ async function startDevServer() {
 }
 ```
 
-完整用法可参考：[示例](https://github.com/rspack-contrib/rspack-examples/blob/main/rsbuild/express/server.mjs)。
+更多用法可参考：
+
+- [示例代码](https://github.com/rspack-contrib/rspack-examples/blob/main/rsbuild/express/server.mjs)。
+- [rsbuild.createDevServer](/api/javascript-api/instance#rsbuildcreatedevserver)
+- [server.middlewareMode](/config/server/middleware-mode)
 
 ### connectWebSocket
 

diff --git a/website/docs/zh/community/releases/v0-5.mdx b/website/docs/zh/community/releases/v0-5.mdx
@@ -50,7 +50,13 @@ import { createRsbuild } from '@rsbuild/core';
 
 async function startCustomServer() {
   const app = express();
-  const rsbuild = await createRsbuild();
+  const rsbuild = await createRsbuild({
+    rsbuildConfig: {
+      server: {
+        middlewareMode: true,
+      },
+    },
+  });
   const { port, middlewares } = await rsbuild.createDevServer();
 
   app.use(middlewares);

diff --git a/website/docs/zh/config/server/middleware-mode.mdx b/website/docs/zh/config/server/middleware-mode.mdx
@@ -0,0 +1,39 @@
+# server.middlewareMode
+
+- **类型：** `boolean`
+- **默认值：** `false`
+- **版本：** `>= 1.2.12`
+
+是否以中间件模式来创建 Rsbuild 的 server，这有助于与其他 server 集成。
+
+开启此选项后，Rsbuild 将不会创建 HTTP server。通常你只有在使用 Rsbuild 的 JavaScript API 时，才需要设置此选项。
+
+## 示例
+
+一个典型的使用场景是，你希望将 Rsbuild 的 server 集成到自定义的 server 中。可以结合 `server.middlewareMode` 和 [rsbuild.createDevServer](/api/javascript-api/instance#rsbuildcreatedevserver) 来实现。
+
+```ts
+import { createRsbuild } from '@rsbuild/core';
+import express from 'express';
+
+async function startDevServer() {
+  // 以 middleware mode 初始化 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);
+}
+```
+
+> 查看 [与自定义 server 集成](/api/javascript-api/dev-server-api#与自定义-server-集成) 了解更多。
diff --git a/website/docs/zh/guide/migration/vite.mdx b/website/docs/zh/guide/migration/vite.mdx
@@ -137,6 +137,7 @@ Rsbuild 会在构建时自动注入 `<script>` 标签到生成的 HTML 文件中
 | server.proxy, preview.proxy           | [server.proxy](/config/server/proxy)                             |
 | server.headers, preview.headers       | [server.headers](/config/server/headers)                         |
 | server.hmr                            | [dev.hmr](/config/dev/hmr), [dev.client](/config/dev/client)     |
+| server.middlewareMode                 | [server.middlewareMode](/config/server/middleware-mode)          |
 | build.target, build.cssTarget         | [Browserslist](/guide/advanced/browserslist)                     |
 | build.outDir, build.assetsDir         | [output.distPath](/config/output/dist-path)                      |
 | build.assetsInlineLimit               | [output.dataUriLimit](/config/output/data-uri-limit)             |