@modern-js/main-doc 2.59.0 → 2.60.1-alpha.0

package/docs/zh/configure/app/tools/dev-server.mdx

@@ -4,6 +4,439 @@ title: devServer
 
 # tools.devServer
 
-import Main from '@modern-js/builder-doc/docs/zh/config/tools/devServer.md';
+- **类型：** `Object`
+- **默认值：** `{}`
 
-<Main />
+通过 `tools.devServer` 可以修改开发环境服务器的配置。
+
+:::tip
+Modern.js 中并没有直接使用 [webpack-dev-server](https://webpack.js.org/api/webpack-dev-server/) 或 [@rspack/dev-server](https://www.rspack.dev/guide/dev-server.html), 而是基于 [webpack-dev-middleware](https://github.com/webpack/webpack-dev-middleware) 实现 DevServer。
+:::
+
+### 选项
+
+#### after
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 [dev.setupMiddlewares](https://modernjs.dev/configure/app/dev/setup-middlewares) 代替。
+:::
+
+- **类型：** `Array`
+- **默认值：** `[]`
+
+添加自定义中间件，在所有开发环境中间件后执行。
+
+```js
+export default {
+  tools: {
+    devServer: {
+      after: [
+        async (req, res, next) => {
+          console.log('after dev middleware');
+          next();
+        },
+      ],
+    },
+  },
+};
+```
+
+`webpack-dev-server` 使用 Express 作为服务端框架。Modern.js 中没有使用任何框架，上述中间件中 `req` 和 `res` 都是 Node 原生对象，因此 `webpack-dev-server` 的 Express 中间件不一定能直接在 Modern.js 中使用。
+
+如果要迁移 `webpack-dev-server` 中使用的 Express 中间件，可以使用以下方式，将 Express app 作为中间件传入：
+
+```js
+import expressMiddleware from 'my-express-middleware';
+import express from 'express';
+
+// 初始化 Express app
+const app = express();
+app.use(expressMiddleware);
+
+export default {
+  tools: {
+    devServer: {
+      after: [app],
+    },
+  },
+};
+```
+
+#### before
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 [dev.setupMiddlewares](https://modernjs.dev/configure/app/dev/setup-middlewares) 代替。
+:::
+
+- **类型：** `Array`
+- **默认值：** `[]`
+
+添加自定义中间件，在所有开发环境中间件前执行。
+
+```js
+export default {
+  tools: {
+    devServer: {
+      before: [
+        async (req, res, next) => {
+          console.log('before dev middleware');
+          next();
+        },
+      ],
+    },
+  },
+};
+```
+
+#### client
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 [dev.client](https://modernjs.dev/configure/app/dev/client) 代替。
+:::
+
+- **类型：**
+
+```ts
+{
+    /** 指定协议名称 */
+    protocol?: string;
+    /** 事件流路径 */
+    path?: string;
+    /** 指定监听请求的端口号 */
+    port?: string;
+    /** 指定要使用的 host */
+    host?: string;
+}
+```
+
+- **默认值：**
+
+```js
+const defaultConfig = {
+  path: '/webpack-hmr',
+  // By default it is set to the port number of the dev server
+  port: '',
+  // By default it is set to "location.hostname"
+  host: '',
+  // By default it is set to "location.protocol === 'https:' ? 'wss' : 'ws'""
+  protocol: '',
+};
+```
+
+对应 HMR 客户端的配置，通常用于设置 HMR 对应的 WebSocket URL。
+
+#### compress
+
+- **类型：** `boolean`
+- **默认值：** `true`
+
+是否对静态资源启用 gzip 压缩。
+
+如果你需要禁用 gzip 压缩，可以将 `compress` 设置为 `false`：
+
+```ts
+export default {
+  tools: {
+    devServer: {
+      compress: false,
+    },
+  },
+};
+```
+
+#### devMiddleware
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 [dev.writeToDisk](https://modernjs.dev/configure/app/dev/write-to-disk) 代替。
+:::
+
+- **类型：**
+
+```js
+{
+  writeToDisk: boolean | ((filename: string) => boolean);
+}
+```
+
+- **默认值：**
+
+```js
+{
+  writeToDisk: (file: string) => !file.includes('.hot-update.'),
+}
+```
+
+devMiddleware 配置项。当前配置是 [webpack-dev-middleware](https://github.com/webpack/webpack-dev-middleware) 配置项的子集.
+
+#### headers
+
+- **类型：** `Record<string, string>`
+- **默认值：** `undefined`
+
+设置自定义响应头。
+
+```js
+export default {
+  tools: {
+    devServer: {
+      headers: {
+        'X-Custom-Foo': 'bar',
+      },
+    },
+  },
+};
+```
+
+#### historyApiFallback
+
+- **类型：** `boolean | ConnectHistoryApiFallbackOptions`
+- **默认值：** `false`
+
+在需要对一些 404 响应或其他请求提供替代页面的场景，可通过 `devServer.historyApiFallback` 进行设置：
+
+```js
+export default {
+  tools: {
+    devServer: {
+      historyApiFallback: true,
+    },
+  },
+};
+```
+
+更多选项和详细信息可参考 [connect-history-api-fallback](https://github.com/bripkens/connect-history-api-fallback) 文档。
+
+#### hot
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 [dev.hmr](https://modernjs.dev/configure/app/dev/hmr) 代替。
+:::
+
+- **类型：** `boolean`
+- **默认值：** `true`
+
+是否开启 [Hot Module Replacement](https://webpack.js.org/concepts/hot-module-replacement/) 热更新能力。
+
+#### https
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 [dev.https](https://modernjs.dev/configure/app/dev/https) 代替。
+:::
+
+- **类型：** `boolean | { key: string; cert: string }`
+- **默认值：** `false`
+
+默认情况下，DevServer 会启用 HTTP 服务器。通过设置 `devServer.https` 为 `true` 将开启对 HTTPS 的支持，同时会禁用 HTTP 服务器。
+
+你也可以手动传入 HTTPS 服务器所需要的证书和对应的私钥：
+
+```js
+export default {
+  tools: {
+    devServer: {
+      https: {
+        key: fs.readFileSync('certificates/private.pem'),
+        cert: fs.readFileSync('certificates/public.pem'),
+      },
+    },
+  },
+};
+```
+
+#### liveReload
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 [dev.liveReload](https://modernjs.dev/configure/app/dev/live-reload) 代替。
+:::
+
+- **类型：** `boolean`
+- **默认值：** `true`
+
+默认情况下，当监听到文件变化时，DevServer 将会刷新页面（为使 liveReload 能够生效，`devServer.hot` 配置项应当禁用）。通过设置 `devServer.liveReload` 为 `false` 可以关闭该行为。
+
+#### setupMiddlewares
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 [dev.setupMiddlewares](https://modernjs.dev/configure/app/dev/setup-middlewares) 代替。
+:::
+
+- **类型：**
+
+```js
+Array<
+  (
+    middlewares: {
+      unshift: (...handlers: RequestHandler[]) => void;
+      push: (...handlers: RequestHandler[]) => void;
+    },
+    server: {
+      sockWrite: (
+        type: string,
+        data?: string | boolean | Record<string, any>,
+      ) => void;
+    },
+  ) => void
+>;
+```
+
+- **默认值：** `undefined`
+
+提供执行自定义函数和应用自定义中间件的能力。
+
+几种不同中间件之间的执行顺序是: `devServer.before` => `unshift` => 内置中间件 => `push` => `devServer.after`。
+
+```js
+export default {
+  tools: {
+    devServer: {
+      setupMiddlewares: [
+        (middlewares, server) => {
+          middlewares.unshift((req, res, next) => {
+            next();
+          });
+
+          middlewares.push((req, res, next) => {
+            next();
+          });
+        },
+      ],
+    },
+  },
+};
+```
+
+一些特殊场景需求可能需要使用服务器 API：
+
+- sockWrite。允许向 hmr 客户端传递一些消息，hmr 客户端将根据接收到的消息类型进行不同的处理。如果你发送一个 "content-changed " 的消息，页面将会重新加载。
+
+```js
+export default {
+  tools: {
+    devServer: {
+      setupMiddlewares: [
+        (middlewares, server) => {
+          // 添加自定义 watcher 并在文件更新时触发页面刷新
+          watcher.on('change', changed => {
+            server.sockWrite('content-changed');
+          });
+        },
+      ],
+    },
+  },
+};
+```
+
+#### proxy
+
+- **类型：** `Record<string, string> | Record<string, ProxyDetail>`
+- **默认值：** `undefined`
+
+代理请求到指定的服务上。
+
+```js
+export default {
+  tools: {
+    devServer: {
+      proxy: {
+        '/api': 'http://localhost:3000',
+      },
+    },
+  },
+};
+```
+
+此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
+
+如果你不想传递 /api，可以通过 `pathRewrite` 重写请求路径：
+
+```js
+export default {
+  tools: {
+    devServer: {
+      proxy: {
+        '/api': {
+          target: 'http://localhost:3000',
+          pathRewrite: { '^/api': '' },
+        },
+      },
+    },
+  },
+};
+```
+
+DevServer Proxy 基于 [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware/tree/2.x) 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
+
+DevServer Proxy 完整类型定义为：
+
+```ts
+import type { Options as HttpProxyOptions } from 'http-proxy-middleware';
+
+type Filter = string | string[] | ((pathname: string, req: Request) => boolean);
+
+type ProxyDetail = HttpProxyOptions & {
+  bypass?: (
+    req: IncomingMessage,
+    res: ServerResponse,
+    proxyOptions: ProxyOptions,
+  ) => string | undefined | null | false;
+  context?: Filter;
+};
+
+type ProxyOptions =
+  | Record<string, string>
+  | Record<string, ProxyDetail>
+  | ProxyDetail[]
+  | ProxyDetail;
+```
+
+除了 http-proxy-middleware 的选项外，还支持 bypass 和 context 两个配置项：
+
+- bypass：根据函数的返回值绕过代理。
+  - 返回 `null` 或 `undefined` 会继续用代理处理请求。
+  - 返回 `false` 会返回 404 错误。
+  - 返回一个具体的服务路径，将会使用此路径替代原请求路径。
+- context：如果你想代理多个特定的路径到同一个目标，你可以使用 context 配置项。
+
+```js
+// 自定义 bypass 方法
+export default {
+  tools: {
+    devServer: {
+      proxy: {
+        '/api': {
+          target: 'http://localhost:3000',
+          bypass: function (req, res, proxyOptions) {
+            if (req.headers.accept.indexOf('html') !== -1) {
+              console.log('Skipping proxy for browser request.');
+              return '/index.html';
+            }
+          },
+        },
+      },
+    },
+  },
+};
+```
+
+```js
+// 代理多个路径到同一个目标
+export default {
+  tools: {
+    devServer: {
+      proxy: [
+        {
+          context: ['/auth', '/api'],
+          target: 'http://localhost:3000',
+        },
+      ],
+    },
+  },
+};
+```
+
+#### watch
+
+- **类型：** `boolean`
+- **默认值：** `true`
+
+是否监听 `mock/`、`server/`、`api/` 等目录的文件变化。

package/docs/zh/configure/app/tools/esbuild.mdx

@@ -16,7 +16,7 @@ title: esbuild
 
 ## 介绍
 
-import Esbuild from '@modern-js/builder-doc/docs/zh/shared/esbuild.md';
+import Esbuild from '@site-docs/components/esbuild.mdx';
 
 <Esbuild />
 
@@ -41,4 +41,4 @@ export default defineConfig({
 });
 ```
 
-完整配置项请参考 [esbuild 插件配置](/guides/rsbuild-plugins/plugin-esbuild.html#配置)。
+完整配置项请参考 [esbuild 插件配置](/plugin/rsbuild-plugins/plugin-esbuild#配置)。

package/docs/zh/configure/app/tools/html-plugin.mdx

@@ -1,9 +1,28 @@
 ---
 title: htmlPlugin
+configName: tools.htmlPlugin
 ---
 
 # tools.htmlPlugin
 
-import Main from '@modern-js/builder-doc/docs/zh/config/tools/htmlPlugin.md';
+- **类型：** `boolean | Object | Function`
+- **默认值：**
 
-<Main />
+```js
+const defaultOptions = {
+  meta, // 对应 `html.meta` 配置
+  title, // 对应 `html.title` 配置
+  inject, // 对应 `html.inject` 配置
+  favicon, // 对应 `html.favicon` 配置
+  template, // 对应 `html.template` 配置
+  filename, // 基于 `output.distPath` 和 `entryName` 生成
+  templateParameters, // 对应 `html.templateParameters` 配置
+  chunks: [entryName],
+};
+```
+
+通过 `tools.htmlPlugin` 可以修改 [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin) 或 [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) 的配置项。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/tools/less.mdx

@@ -4,6 +4,83 @@ title: less
 
 # tools.less
 
-import Main from '@modern-js/builder-doc/docs/zh/config/tools/less.md';
+- **类型：** `Object | Function`
+- **默认值：**
+
+```js
+const defaultOptions = {
+  lessOptions: {
+    javascriptEnabled: true,
+  },
+  // 默认在开发环境下启用 CSS 的 Source Map
+  sourceMap: isDev,
+};
+```
+
+你可以通过 `tools.less` 修改 [less-loader](https://github.com/webpack-contrib/less-loader) 的配置。
+
+### Object 类型
+
+当 `tools.less` 的值为 `Object` 类型时，会与默认配置通过 Object.assign 进行浅层合并，值得注意的是，`lessOptions` 会通过 deepMerge 进行深层合并。
+
+```js
+export default {
+  tools: {
+    less: {
+      lessOptions: {
+        javascriptEnabled: false,
+      },
+    },
+  },
+};
+```
+
+### Function 类型
+
+当 `tools.less` 为 Function 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果，第二个参数提供了一些可以直接调用的工具函数：
+
+```js
+export default {
+  tools: {
+    less(config) {
+      // 修改 lessOptions 配置
+      config.lessOptions = {
+        javascriptEnabled: false,
+      };
+    },
+  },
+};
+```
+
+### 修改 Less 版本
+
+在某些场景下，如果你需要使用特定的 Less 版本，而不是使用 Modern.js 内置的 Less v4，可以在项目中安装需要使用的 Less 版本，并通过 `less-loader` 的 `implementation` 选项设置。
+
+```js
+export default {
+  tools: {
+    less: {
+      implementation: require('less'),
+    },
+  },
+};
+```
+
+### 工具函数
+
+#### addExcludes
+
+- **类型：** `(excludes: RegExp | RegExp[]) => void`
+
+用来指定 `less-loader` 不编译哪些文件，你可以传入一个或多个正则表达式来匹配 less 文件的路径。例如：
+
+```js
+export default {
+  tools: {
+    less(config, { addExcludes }) {
+      addExcludes(/node_modules/);
+    },
+  },
+};
+```
 
-<Main />

package/docs/zh/configure/app/tools/minify-css.mdx

@@ -4,6 +4,54 @@ title: minifyCss
 
 # tools.minifyCss
 
-import Main from '@modern-js/builder-doc/docs/zh/config/tools/minifyCss.md';
+- **类型：** `Object | Function | undefined`
+- **默认值：**
 
-<Main />
+```js
+const defaultOptions = {
+  minimizerOptions: {
+    preset: [
+      'default',
+      {
+        mergeLonghand: false,
+      },
+    ],
+  },
+};
+```
+
+在生产环境构建时，Modern.js 会通过 [css-minimizer-webpack-plugin](https://github.com/webpack-contrib/css-minimizer-webpack-plugin) 对 CSS 代码进行压缩优化。可以通过 `tools.minifyCss` 修改 [css-minimizer-webpack-plugin](https://github.com/webpack-contrib/css-minimizer-webpack-plugin) 的配置。
+
+### Object 类型
+
+当 `tools.minifyCss` 的值为 `Object` 类型时，会与默认配置通过 `Object.assign` 合并。
+
+例如下面修改 [cssnano](https://cssnano.co/) 的 `preset` 配置：
+
+```js
+export default {
+  tools: {
+    minifyCss: {
+      minimizerOptions: {
+        preset: require.resolve('cssnano-preset-simple'),
+      },
+    },
+  },
+};
+```
+
+### Function 类型
+
+当 `tools.minifyCss` 配置为 `Function` 类型时，默认配置作为第一个参数传入，可以直接修改配置对象，也可以返回一个值作为最终结果。
+
+```js
+export default {
+   tools: {
+    minifyCss: options => {
+      options.minimizerOptions = {
+        preset: require.resolve('cssnano-preset-simple'),
+      },
+    }
+  }
+};
+```

package/docs/zh/configure/app/tools/postcss.mdx

@@ -1,9 +1,38 @@
 ---
 title: postcss
+configName: tools.postcss
 ---
 
 # tools.postcss
 
-import Main from '@modern-js/builder-doc/docs/zh/config/tools/postcss.md';
+- **类型：** `Object | Function`
+- **默认值：**
 
-<Main />
+```js
+const defaultOptions = {
+  postcssOptions: {
+    plugins: [
+      // 以下插件默认启用
+      require('postcss-nesting'),
+      require('postcss-media-minmax'),
+      require('postcss-flexbugs-fixes'),
+      require('autoprefixer')({
+        flexbox: 'no-2009',
+      }),
+      // 以下插件仅在需要兼容低版本浏览器时启用
+      require('postcss-custom-properties'),
+      require('postcss-initial'),
+      require('postcss-page-break'),
+      require('postcss-font-variant'),
+    ],
+    // 默认在开发环境下启用 CSS 的 Source Map
+    sourceMap: isDev,
+  },
+};
+```
+
+Modern.js 默认集成 PostCSS，你可以通过 `tools.postcss` 对 [postcss-loader](https://github.com/webpack-contrib/postcss-loader) 进行配置。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />