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

package/docs/zh/components/rspack.mdx

@@ -0,0 +1,3 @@
+[Rspack](https://www.rspack.dev/) 是一个基于 Rust 编写的高性能 JavaScript 打包工具， 它提供对 webpack 生态良好的兼容性，能够无缝替换 webpack， 并提供闪电般的构建速度。
+
+相较于 webpack，Rspack 的构建性能有明显提升，除了 Rust 带来的语言优势，这也来自于它的并行架构和增量编译等特性。经过 benchmark 验证，Rspack 可以带来 5 ～ 10 倍编译性能的提升。

package/docs/zh/components/rspackPrecautions.mdx

@@ -0,0 +1,6 @@
+## 注意事项
+
+在使用 Rspack 前，你需要了解以下事项：
+
+- Rspack 能够兼容大部分 webpack 插件和几乎所有的 loaders，但仍有少数 webpack 插件暂时无法使用，详见 [Plugin 兼容](https://rspack.dev/zh/guide/compatibility/plugin)。
+- Rspack 默认基于 [SWC](https://rspack.dev/zh/guide/features/builtin-swc-loader) 进行代码编译和压缩，在个别情况下，你可能会遇到 SWC 在边界场景的 bug，可以通过 [SWC 的 issue](https://github.com/swc-project/swc/issues) 反馈。

package/docs/zh/components/rspackTip.mdx

@@ -0,0 +1,7 @@
+:::tip Rspack - 高性能 Web 构建工具
+
+import Rspack from './rspack.mdx';
+
+<Rspack />
+
+:::

package/docs/zh/components/swc.mdx

@@ -0,0 +1,3 @@
+[SWC](https://swc.rs/) (Speedy Web Compiler) 是基于 `Rust` 语言编写的高性能 JavaScript 和 TypeScript 转译和压缩工具。在 Polyfill 和语法降级方面可以和 Babel 提供一致的能力，并且性能比 Babel 高出一个数量级。
+
+Modern.js 提供了开箱即用的 SWC 插件，可以为你的 Web 应用提供语法降级、Polyfill 以及压缩，并且移植了一些额外常见的 Babel 插件。

package/docs/zh/configure/app/auto-load-plugin.mdx

@@ -9,6 +9,10 @@ sidebar_position: 22
 
 用于配置 Modern.js 是否开启自动注册插件。
 
+:::warning
+该配置不推荐使用，相比手动注册插件，该配置相对黑盒且无法为插件添加自定义配置。
+:::
+
 ### 手动注册插件
 
 默认情况下，安装插件后，你需要在 `modern.config.ts` 文件中手动注册插件。

package/docs/zh/configure/app/dev/asset-prefix.mdx

@@ -1,9 +1,19 @@
 ---
 title: assetPrefix
+configName: dev.assetPrefix
 ---
 
 # dev.assetPrefix
 
-import Main from '@modern-js/builder-doc/docs/zh/config/dev/assetPrefix.md';
+- **类型：** `boolean | string | 'auto'`
+- **默认值：** `'/'`
 
-<Main />
+此配置项用于设置 **开发模式** 下的静态资源 URL 前缀。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />
+
+:::warning
+请注意，该配置项仅适用于开发模式。在生产模式下，请使用 [output.assetPrefix](/configure/app/output/asset-prefix) 配置项进行设置。
+:::

package/docs/zh/configure/app/dev/before-start-url.mdx

@@ -4,6 +4,18 @@ title: beforeStartUrl
 
 # dev.beforeStartUrl
 
-import Main from '@modern-js/builder-doc/docs/zh/config/dev/beforeStartUrl.md';
+- **类型：** `() => Promise<void> | void`
+- **默认值：** `undefined`
 
-<Main />
+`dev.beforeStartUrl` 用于在打开 `startUrl` 前执行一段回调函数，该配置项需要与 [`dev.startUrl`](/configure/app/dev/start-url) 一同使用。
+
+```js
+export default {
+  dev: {
+    startUrl: true,
+    beforeStartUrl: async () => {
+      await doSomeThing();
+    },
+  },
+};
+```

package/docs/zh/configure/app/dev/client.mdx

@@ -1,27 +1,25 @@
 ---
 title: client
+configName: dev.client
 ---
 
 # dev.client
 
-配置 Modern.js 在开发过程中注入的 client 代码，可以用于设置热更新对应的 WebSocket URL。
-
 - **类型：**
 
 ```ts
 type Client = {
-  /** 指定 WebSocket 请求的协议名称 */
+  // WebSocket 请求的协议名称
   protocol?: 'ws' | 'wss';
-  /** 指定 WebSocket 请求的路径 */
+  // WebSocket 请求的路径
   path?: string;
-  /** 指定 WebSocket 请求的端口号 */
-  port?: string;
-  /** 指定 WebSocket 请求的 host */
+  // WebSocket 请求的端口号
+  port?: string | number;
+  // WebSocket 请求的 host
   host?: string;
-  /**
-   * 当出现编译错误时，在浏览器中显示遮盖
-   * 该功能需要当前浏览器版本支持 [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)
-   */
+  // WebSocket 请求断开后的最大重连次数
+  reconnect?: number;
+  // 当出现编译错误时，是否在浏览器中显示 error overlay
   overlay?: boolean;
 };
 ```
@@ -31,12 +29,18 @@ type Client = {
 ```js
 const defaultConfig = {
   path: '/webpack-hmr',
-  // 默认为开发服务器的端口号
-  port: '',
-  host: location.hostname,
-  protocol: location.protocol === 'https:' ? 'wss' : 'ws',
+  port: '<port>',
+  // 默认为 "location.hostname"
+  host: '',
+  // 默认为 "location.protocol === 'https:' ? 'wss' : 'ws'""
+  protocol: undefined,
+  reconnect: 100,
   overlay: false,
 };
 ```
 
-详细用法可参考 [Rsbuild - dev.client](https://rsbuild.dev/zh/config/dev/client)。
+配置 Modern.js 在开发过程中注入的 client 代码，可以用于设置热更新对应的 WebSocket URL。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/dev/hmr.mdx

@@ -1,9 +1,15 @@
 ---
 title: hmr
+configName: dev.hmr
 ---
 
 # dev.hmr
 
-import Main from '@modern-js/builder-doc/docs/zh/config/dev/hmr.md';
+- **类型：** `boolean`
+- **默认值：** `true`
 
-<Main />
+是否开启 Hot Module Replacement 热更新能力。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/dev/host.mdx

@@ -4,6 +4,19 @@ title: host
 
 # dev.host
 
-import Main from '@modern-js/builder-doc/docs/zh/config/dev/host.md';
+- **类型：** `string`
+- **默认值：** `0.0.0.0`
 
-<Main />
+指定 dev server 启动时监听的 host。
+
+默认情况下，dev server 会监听 `0.0.0.0`，这代表监听所有的网络接口，包括 `localhost` 和公网地址。
+
+如果你希望 dev server 只监听 `localhost`，可以设置为：
+
+```ts
+export default {
+  dev: {
+    host: 'localhost',
+  },
+};
+```

package/docs/zh/configure/app/dev/https.mdx

@@ -4,6 +4,76 @@ title: https
 
 # dev.https
 
-import Main from '@modern-js/builder-doc/docs/zh/config/dev/https.md';
+- **类型：** `boolean | { key: string; cert: string }`
+- **默认值：** `false`
+
+配置该选项后，可以开启 Dev Server 对 HTTPS 的支持，同时会禁用 HTTP 服务器。
+
+开启前：
+
+```bash
+  > Local:    http://localhost:8080/
+  > Network:  http://192.168.0.1:8080/
+```
+
+开启后：
+
+```bash
+  > Local:    https://localhost:8080/
+  > Network:  https://192.168.0.1:8080/
+```
+
+#### 自动生成证书
+
+你可以直接将 `https` 设置为 `true`，Modern.js 会基于 [devcert](https://github.com/davewasmer/devcert) 来自动生成 Dev Server 所需的 HTTPS 证书。
+
+使用这种方式时，你需要在当前项目中手动安装 [devcert](https://github.com/davewasmer/devcert) 依赖：
+
+```bash
+# npm
+npm install devcert@1.2.2 -D
+
+# yarn
+yarn add devcert@1.2.2 -D
+
+# pnpm
+pnpm add devcert@1.2.2 -D
+```
+
+然后配置 `dev.https` 为 `true` 即可：
+
+```ts
+export default {
+  dev: {
+    https: true,
+  },
+};
+```
+
+该方式有一定局限性，由于 devcert 目前不支持 IP addresses，因此访问 Network 域名时，会遇到「您的连接不是私密连接」的问题。
+
+此问题的解决方法为：点击 Chrome 浏览器问题页面的「高级」->「继续前往 192.168.0.1（不安全）」。
+
+:::tip
+https 代理自动安装证书需要获取 root 权限, 请根据提示输入密码即可。 **密码仅在信任证书时使用，不会泄漏或者用于其他环节**。
+:::
+
+#### 手动设置证书
+
+你也可以在 `dev.https` 选项中手动传入 HTTPS 服务器所需要的证书和对应的私钥，这个参数将直接传递给 Node.js 中 https 模块的 createServer。
+
+具体可以参考 [https.createServer](https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener)。
+
+```ts
+import fs from 'fs';
+
+export default {
+  dev: {
+    https: {
+      key: fs.readFileSync('certificates/private.pem'),
+      cert: fs.readFileSync('certificates/public.pem'),
+    },
+  },
+};
+```
 
-<Main />

package/docs/zh/configure/app/dev/live-reload.mdx

@@ -1,5 +1,6 @@
 ---
 title: liveReload
+configName: dev.liveReload
 ---
 
 # dev.liveReload
@@ -9,19 +10,6 @@ title: liveReload
 
 是否在源文件变更时自动刷新页面。
 
-默认情况下，Modern.js 会优先使用 HMR 来更新模块。当 HMR 功能被禁用，或者某些场景 HMR 无法生效时，会自动降级到 liveReload。
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
 
-请查看 [模块热更新](https://rsbuild.dev/zh/guide/advanced/hmr) 来了解更多内容。
-
-## 禁用 liveReload
-
-如果你需要禁用 liveReload，可以将 `dev.hmr` 和 `dev.liveReload` 同时设置为 `false`，此时页面上不会发起 Web Socket 请求到 dev server，也不会在文件变更时自动刷新页面。
-
-```js
-export default {
-  dev: {
-    hmr: false,
-    liveReload: false,
-  },
-};
-```
+<RsbuildConig />

package/docs/zh/configure/app/dev/port.mdx

@@ -4,6 +4,22 @@ title: port
 
 # dev.port
 
-import Main from '@modern-js/builder-doc/docs/zh/config/dev/port.md';
+- **类型：** `number`
+- **默认值：** `8080`
+
+设置 Dev Server 监听的端口号。
+
+默认情况下，Dev Server 会监听 8080 端口，并在端口被占用时自动递增端口号。
+
+### 示例
+
+将端口设置为 `3000`：
+
+```ts
+export default {
+  dev: {
+    port: 3000,
+  },
+};
+```
 
-<Main />

package/docs/zh/configure/app/dev/progress-bar.mdx

@@ -1,9 +1,24 @@
 ---
 title: progressBar
+configName: dev.progressBar
 ---
 
 # dev.progressBar
 
-import Main from '@modern-js/builder-doc/docs/zh/config/dev/progressBar.md';
+- **类型：**
 
-<Main />
+```ts
+type ProgressBar =
+  | boolean
+  | {
+      id?: string;
+    };
+```
+
+- **默认值：** true
+
+是否在编译过程中展示进度条。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/dev/setup-middlewares.mdx

@@ -1,5 +1,6 @@
 ---
 title: setupMiddlewares
+configName: dev.setupMiddlewares
 ---
 
 # dev.setupMiddlewares
@@ -7,11 +8,32 @@ title: setupMiddlewares
 - **类型：**
 
 ```ts
-type ServerAPIs = {
+type SetupMiddlewaresServer = {
   sockWrite: (
     type: string,
     data?: string | boolean | Record<string, any>,
   ) => void;
+  environments: {
+    [name: string]: {
+      /**
+       * 获取当前环境的构建信息
+       */
+      getStats: () => Promise<Stats>;
+
+      /**
+       * 在服务端加载并执行构建产物
+       *
+       * @param entryName - 入口名称，和 Rsbuild source.entry 的某一个 key 值对应
+       * @returns 入口模块的返回值
+       */
+      loadBundle: <T = unknown>(entryName: string) => Promise<T>;
+
+      /**
+       * 获取编译后的 HTML 模版内容
+       */
+      getTransformedHtml: (entryName: string) => Promise<string>;
+    };
+  };
 };
 
 type SetupMiddlewares = Array<
@@ -20,7 +42,7 @@ type SetupMiddlewares = Array<
       unshift: (...handlers: RequestHandler[]) => void;
       push: (...handlers: RequestHandler[]) => void;
     },
-    server: ServerAPIs,
+    server: SetupMiddlewaresServer,
   ) => void
 >;
 ```
@@ -29,41 +51,6 @@ type SetupMiddlewares = Array<
 
 提供执行自定义函数和应用自定义中间件的能力。
 
-中间件的执行顺序是: `unshift` => 内置中间件 => `push`。
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
 
-```js
-export default {
-  dev: {
-    setupMiddlewares: [
-      (middlewares, server) => {
-        middlewares.unshift((req, res, next) => {
-          next();
-        });
-
-        middlewares.push((req, res, next) => {
-          next();
-        });
-      },
-    ],
-  },
-};
-```
-
-一些特殊场景需求可能需要使用服务器 API：
-
-- sockWrite。允许向 HMR 客户端传递一些消息，HMR 客户端将根据接收到的消息类型进行不同的处理。如果你发送一个 "content-changed " 的消息，页面将会重新加载。
-
-```js
-export default {
-  dev: {
-    setupMiddlewares: [
-      (middlewares, server) => {
-        // 添加自定义 watcher 并在文件更新时触发页面刷新
-        watcher.on('change', (changed) => {
-          server.sockWrite('content-changed');
-        });
-      },
-    ],
-  },
-};
-```
+<RsbuildConig />

package/docs/zh/configure/app/dev/start-url.mdx

@@ -4,6 +4,51 @@ title: startUrl
 
 # dev.startUrl
 
-import Main from '@modern-js/builder-doc/docs/zh/config/dev/startUrl.md';
+- **类型：** `boolean | string | string[] | undefined`
+- **默认值：** `undefined`
 
-<Main />
+`dev.startUrl` 用于设置 Dev Server 启动时自动在浏览器中打开的页面 URL。
+
+默认情况下，Dev Server 启动时不会打开任何页面。
+
+你可以设置为如下的值：
+
+```js
+export default {
+  dev: {
+    // 打开项目的默认页面，等价于 `http://localhost:<port>`
+    startUrl: true,
+    // 打开指定的页面
+    startUrl: 'http://localhost:8080',
+    // 打开多个页面
+    startUrl: ['http://localhost:8080', 'http://localhost:8080/about'],
+  },
+};
+```
+
+### 端口号占位符
+
+由于端口号可能会发生变动，你可以使用 `<port>` 占位符来指代当前端口号，Modern.js 会自动将占位符替换为实际监听的端口号。
+
+```js
+export default {
+  dev: {
+    startUrl: 'http://localhost:<port>/home',
+  },
+};
+```
+
+### 打开指定浏览器
+
+在 MacOS 上，通过设置环境变量 `BROWSER`，你可以指定 Dev Server 在启动时打开的浏览器，支持如下的值：
+
+- Google Chrome Canary
+- Google Chrome Dev
+- Google Chrome Beta
+- Google Chrome
+- Microsoft Edge
+- Brave Browser
+- Vivaldi
+- Chromium
+
+建议设置在`.env.local`文件中。

package/docs/zh/configure/app/dev/watch-files.mdx

@@ -1,5 +1,6 @@
 ---
 title: watchFiles
+configName: dev.watchFiles
 ---
 
 # dev.watchFiles
@@ -9,6 +10,7 @@ title: watchFiles
 ```ts
 type WatchFiles = {
   paths: string | string[];
+  type?: 'reload-page' | 'reload-server';
   //  chokidar 选项
   options?: WatchOptions;
 };
@@ -16,44 +18,8 @@ type WatchFiles = {
 
 - **默认值：** `undefined`
 
-监视指定文件和目录的变化。当文件发生变化时，页面将重新加载。
+监听指定文件和目录的变化。当文件发生变化时，可以触发页面的重新加载，或者触发 dev server 重新启动。
 
-如果 `dev.hmr` 和 `dev.liveReload` 都设置为 false，则 `watchFiles` 将被忽略。
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
 
-:::tip
-WatchFiles 中文件发生变化时，不会触发配置文件的重新加载及重新编译。
-:::
-
-### 示例
-
-你可以配置一个 glob 模式 / 目录 / 文件的列表，用于监视文件变化。
-
-```js
-export default {
-  dev: {
-    watchFiles: {
-      // 监视单个文件
-      paths: 'public/demo.txt',
-      // 使用 glob 模式
-      paths: 'src/**/*.txt',
-      // 监视多个文件路径
-      paths: ['src/**/*.txt', 'public/**/*'],
-    },
-  },
-};
-```
-
-你也可以通过传入一个包含 `paths` 和 `options` 属性的对象，来指定 [chokidar](https://github.com/paulmillr/chokidar#api) 选项。
-
-```js
-export default {
-  dev: {
-    watchFiles: {
-      paths: 'src/**/*.txt',
-      options: {
-        usePolling: false,
-      },
-    },
-  },
-};
-```
+<RsbuildConig />

package/docs/zh/configure/app/dev/write-to-disk.mdx

@@ -1,5 +1,6 @@
 ---
 title: writeToDisk
+configName: dev.writeToDisk
 ---
 
 # dev.writeToDisk
@@ -9,30 +10,6 @@ title: writeToDisk
 
 用于控制是否将开发环境的构建产物写入到磁盘上。
 
-## 写入内存
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
 
-你可以选择将构建产物构建产物保存在 dev server 的内存中，从而减少文件操作产生的开销。
-
-只需要将 `dev.writeToDisk` 配置项设置为 `false` 即可：
-
-```ts
-export default {
-  dev: {
-    writeToDisk: false,
-  },
-};
-```
-
-## 匹配部分文件
-
-你也可以将 `dev.writeToDisk` 设置为函数来匹配一部分文件，函数返回 `false` 时不会写入文件，返回值 `true` 时会将文件写入磁盘。
-
-例如，Modern.js 会默认将文件写入磁盘，并排除热更新临时文件：
-
-```ts
-export default {
-  dev: {
-    writeToDisk: (file) => !file.includes('.hot-update.'),
-  },
-};
-```
+<RsbuildConig />

package/docs/zh/configure/app/experiments/lazy-compilation.mdx

@@ -4,6 +4,88 @@ title: lazyCompilation
 
 # experiments.lazyCompilation
 
-import Main from '@modern-js/builder-doc/docs/zh/config/experiments/lazyCompilation.md';
+- **类型：**
 
-<Main />
+```ts
+type LazyCompilationOptions =
+  | boolean
+  | {
+      // 是否为异步模块开启延迟编译
+      imports?: boolean;
+      // 是否为入口模块开启延迟编译
+      entries?: boolean;
+      // 指定哪些导入的模块应该被延迟编译
+      test?: RegExp | ((m: Module) => boolean);
+    };
+```
+
+- **默认值：** `false`
+
+用于开启延迟编译（即按需编译）的能力。当开启此配置项时，Modern.js 会进行延迟编译，提升项目的编译启动速度。
+
+延迟编译只在开发环境下生效。
+
+### 延迟编译异步模块
+
+延迟编译 [dynamic import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) 引入的异步模块：
+
+```ts
+export default {
+  experiments: {
+    lazyCompilation: {
+      imports: true,
+      entries: false,
+    },
+  },
+};
+```
+
+开启 `imports` 选项后，所有的异步模块只有在被请求时才触发编译。如果你的项目是一个单页应用（SPA），并通过 dynamic import 进行了路由拆分，那么会有明显的编译提速效果。
+
+### 延迟编译入口模块
+
+除了延迟编译异步模块，你也可以选择同时延迟编译入口模块和异步模块。
+
+```ts
+export default {
+  experiments: {
+    lazyCompilation: {
+      imports: true,
+      entries: true,
+    },
+  },
+};
+```
+
+以上配置也可以简化为：
+
+```ts
+export default {
+  experiments: {
+    lazyCompilation: true,
+  },
+};
+```
+
+开启 `entries` 选项后，当启动编译时，不会编译所有的页面，而是仅在路由跳转到对应的页面时，才对该页面进行编译。
+
+使用延迟编译入口模块时，有以下注意事项：
+
+- 只适用于多页应用（MPA），对单页应用（SPA）没有优化效果。
+- 当你访问一个页面时，由于要等待页面编译完成，会有一段时间的白屏。
+
+### 局限性
+
+#### 禁用拆包规则
+
+当你开启延迟编译时，为了保证编译结果正常，Modern.js 会在开发环境下禁用拆包规则。这不会影响生产环境的打包产物，但会导致开发环境和生产环境的打包产物有一定差异。
+
+#### 使用代理
+
+Lazy Compilation 依赖 webpack 在本地启动的开发服务器，当你将某个域名代理到 localhost 进行开发时，Lazy Compilation 将无法正常工作。因此，如果你需要使用代理时，请禁用 Lazy Compilation。
+
+#### 其他潜在的问题
+
+考虑到 Lazy Compilation 仍然是 webpack 的实验性功能，因此你在使用过程中，可能会遇到一些潜在的问题，比如编译产物的行为变化，或是编译出现异常。
+
+当你遇到这些问题时，可以参考 [webpack 的 Issues](https://github.com/webpack/webpack/issues) 寻找解决方案，也可以关闭 `lazyCompilation` 配置项。