@modern-js/main-doc 2.60.0 → 2.60.1

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` 配置项。

package/docs/zh/configure/app/experiments/source-build.mdx

@@ -4,6 +4,33 @@ title: sourceBuild
 
 # experiments.sourceBuild
 
-import Main from '@modern-js/builder-doc/docs/zh/config/experiments/sourceBuild.md';
+- **类型：** `boolean | PluginSourceBuildOptions`
+- **默认值：** `false`
+- **版本：** `MAJOR_VERSION.46.0`
 
-<Main />
+用于开启源码构建的能力。当开启此配置项时，Modern.js 会读取子项目 package.json 的 `source` 字段对应的源码文件，并进行编译。
+
+```ts
+export default {
+  experiments: {
+    sourceBuild: true,
+  },
+};
+```
+
+更多信息可参考[「源码构建模式」](https://modernjs.dev/guides/advanced-features/source-build.html)。
+
+### 选项
+
+`experiments.sourceBuild` 底层基于 [@rsbuild/plugin-source-build](https://github.com/rspack-contrib/rsbuild-plugin-source-build?tab=readme-ov-file#options) 实现，你可以传入插件选项，比如：
+
+```ts
+export default {
+  experiments: {
+    sourceBuild: {
+      sourceField: 'my-source',
+      resolvePriority: 'output',
+    },
+  },
+};
+```

package/docs/zh/configure/app/html/app-icon.mdx

@@ -1,9 +1,55 @@
 ---
 title: appIcon
+configName: html.appIcon
 ---
 
 # html.appIcon
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/appIcon.md';
+- **类型：**
 
-<Main />
+```ts
+type AppIconItem = {
+  src: string;
+  size: number;
+  target?: 'apple-touch-icon' | 'web-app-manifest';
+};
+
+type AppIcon = string | {
+  name?: string;
+  icons: AppIconItem[];
+  filename?: string;
+};
+```
+
+- **默认值：** `undefined`
+
+设置 Web 应用的图标，用于在添加到移动设备的主屏幕时显示：
+
+- 生成 web app manifest 文件和其中的 `icons` 字段。
+- 生成 HTML 文件中的 `apple-touch-icon` 标签和 `manifest` 标签。
+
+### 字符串形式
+
+`string` 类型的 `appIcon` 配置是对象类型的一个语法糖。
+
+```js
+export default {
+  html: {
+    appIcon: './src/assets/icon.png',
+  },
+};
+```
+
+以上配置相当于下面配置的语法糖：
+
+```js
+export default {
+  html: {
+    appIcon: { icons: [{ src: './src/assets/icon.png', size: 180 }] }
+  },
+};
+```
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/html/crossorigin.mdx

@@ -1,9 +1,16 @@
 ---
 title: crossorigin
+configName: html.crossorigin
 ---
 
 # html.crossorigin
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/crossorigin.md';
+- **类型：** `boolean | 'anonymous' | 'use-credentials'`
+- **默认值：** `false`
 
-<Main />
+用于设置 `<script>` 和 `<style>` 标签的 [crossorigin](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) 属性。
+
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/html/disable-html-folder.mdx

@@ -4,6 +4,38 @@ title: disableHtmlFolder
 
 # html.disableHtmlFolder
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/disableHtmlFolder.md';
+- **类型：** `boolean`
+- **默认值：** `false`
 
-<Main />
+移除 HTML 产物对应的文件夹。开启该选项后，生成的 HTML 文件目录会从 `[name]/index.html` 变为 `[name].html`。
+
+### 示例
+
+默认情况下，HTML 产物在 `dist` 目录下的结构为：
+
+```bash
+/dist
+└── html
+    └── main
+        └── index.html
+```
+
+开启 `html.disableHtmlFolder` 配置:
+
+```js
+export default {
+  html: {
+    disableHtmlFolder: true,
+  },
+};
+```
+
+重新编译后，HTML 产物在 dist 中的目录结构如下：
+
+```bash
+/dist
+└── html
+    └── main.html
+```
+
+> 如果需要设置 HTML 文件在 dist 目录中的路径，请使用 `output.distPath.html` 配置。

package/docs/zh/configure/app/html/favicon-by-entries.mdx

@@ -4,6 +4,34 @@ title: faviconByEntries
 
 # html.faviconByEntries
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/faviconByEntries.md';
+- **类型：** `Record<string, string>`
+- **默认值：** `undefined`
+
+用于在多页面的场景下，为不同的页面设置不同的 favicon。
+
+整体用法与 `favicon` 一致，并且可以使用「入口名称」作为 key ，对各个页面进行单独设置。
+
+`faviconByEntries` 的优先级高于 `favicon`，因此会覆盖 `favicon` 中设置的值。
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 `html.favicon` 的函数用法代替。
+:::
+
+### 示例
+
+```js
+export default {
+  html: {
+    favicon: './src/assets/default.png',
+    faviconByEntries: {
+      foo: './src/assets/foo.png',
+    },
+  },
+};
+```
+
+重新编译后，可以看到:
+
+- 页面 `foo` 的 favicon 为 `./src/assets/foo.png`。
+- 其他页面的 favicon 为 `./src/assets/default.png`。
 
-<Main />

package/docs/zh/configure/app/html/favicon.mdx

@@ -1,9 +1,22 @@
 ---
 title: favicon
+configName: html.favicon
 ---
 
 # html.favicon
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/favicon.md';
+- **类型：** `string ｜ Function`
+- **默认值：** `undefined`
 
-<Main />
+设置页面的 favicon 图标，可以设置为：
+
+- URL 地址。
+- 文件的绝对路径。
+- 相对于项目根目录的相对路径。
+
+配置该选项后，在编译过程中会自动将图标拷贝至 dist 目录下，并在 HTML 中添加相应的 `link` 标签。
+
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/html/inject-by-entries.mdx

@@ -4,6 +4,34 @@ title: injectByEntries
 
 # html.injectByEntries
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/injectByEntries.md';
+- **类型：** `Record<string, boolean | string>`
+- **默认值：** `undefined`
+
+用于在多页面的场景下，为不同的页面设置不同的 script 标签插入位置。
+
+整体用法与 `inject` 一致，并且可以使用「入口名称」作为 key ，对各个页面进行单独设置。
+
+`injectByEntries` 的优先级高于 `inject`，因此会覆盖 `inject` 中设置的值。
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 `html.inject` 的函数用法代替。
+:::
+
+### 示例
+
+```js
+export default {
+  html: {
+    inject: 'head',
+    injectByEntries: {
+      foo: 'body',
+    },
+  },
+};
+```
+
+重新编译后，可以看到:
+
+- 页面 `foo` 的 script 标签会插入到 `body` 标签内。
+- 其他页面的 script 标签会插入到 `head` 标签内。
 
-<Main />

package/docs/zh/configure/app/html/inject.mdx

@@ -1,9 +1,15 @@
 ---
 title: inject
+configName: html.inject
 ---
 
 # html.inject
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/inject.md';
+- **类型：** `'head' | 'body' | boolean | Function`
+- **默认值：** `'head'`
 
-<Main />
+修改构建产物中 `<script>` 标签在 HTML 中的插入位置。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/html/meta-by-entries.mdx

@@ -4,6 +4,45 @@ title: metaByEntries
 
 # html.metaByEntries
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/metaByEntries.md';
+- **类型：** `Record<string, Meta>`
+- **默认值：** `undefined`
+
+用于在多页面的场景下，为不同的页面设置不同的 meta 标签。
+
+整体用法与 `meta` 一致，并且可以使用「入口名称」作为 key ，对各个页面进行单独设置。
+
+`metaByEntries` 的优先级高于 `meta`，因此会覆盖 `meta` 中设置的值。
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 `html.meta` 的函数用法代替。
+:::
+
+### 示例
+
+```js
+export default {
+  html: {
+    meta: {
+      description: 'ByteDance',
+    },
+    metaByEntries: {
+      foo: {
+        description: 'TikTok',
+      },
+    },
+  },
+};
+```
+
+编译后，可以看到页面 `foo` 的 meta 为：
+
+```html
+<meta name="description" content="TikTok" />
+```
+
+其他页面的 meta 为：
+
+```html
+<meta name="description" content="ByteDance" />
+```
 
-<Main />

package/docs/zh/configure/app/html/meta.mdx

@@ -1,9 +1,29 @@
 ---
 title: meta
+configName: html.meta
 ---
 
 # html.meta
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/meta.md';
+- **类型：** `Object | Function`
+- **默认值：**
 
-<Main />
+```js
+const defaultMeta = {
+  charset: { charset: 'utf-8' },
+  viewport:
+    'width=device-width, initial-scale=1.0, shrink-to-fit=no, viewport-fit=cover, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no',
+  'http-equiv': { 'http-equiv': 'x-ua-compatible', content: 'ie=edge' },
+  renderer: 'webkit',
+  layoutmode: 'standard',
+  imagemode: 'force',
+  'wap-font-scale': 'no',
+  'format-detection': 'telephone=no',
+};
+```
+
+配置 HTML 页面的 `<meta>` 标签。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/html/mount-id.mdx

@@ -1,9 +1,15 @@
 ---
 title: mountId
+configName: html.mountId
 ---
 
 # html.mountId
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/mountId.md';
+- **类型：** `string`
+- **默认值：** `'root'`
 
-<Main />
+默认情况下，HTML 模板中包含了 `root` 节点用于组件挂载，通过 `mountId` 可以修改该节点的 id。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/html/script-loading.mdx

@@ -1,9 +1,15 @@
 ---
 title: scriptLoading
+configName: html.scriptLoading
 ---
 
 # html.scriptLoading
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/scriptLoading.md';
+- **类型：** `'defer' | 'blocking' | 'module'`
+- **默认值：** `'defer'`
 
-<Main />
+用于设置 `<script>` 标签的加载方式。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/html/tags-by-entries.mdx

@@ -4,6 +4,41 @@ title: tagsByEntries
 
 # html.tagsByEntries
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/tagsByEntries.md';
+- **类型：** `Record<string, ArrayOrNot<HtmlInjectTag | HtmlInjectTagHandler>>`
+- **默认值：** `undefined`
+
+用于在多页面的场景下，为不同的页面注入不同的标签。
+
+整体用法与 `tags` 一致，并且可以使用「入口名称」作为 key ，对各个页面进行单独设置。
+
+`tagsByEntries` 的优先级高于 `tags`，因此会覆盖 `tags` 中设置的值。
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 `html.tags` 的函数用法代替。
+:::
+
+### 示例
+
+```js
+export default {
+  html: {
+    tags: [{ tag: 'script', attrs: { src: 'a.js' } }],
+    tagsByEntries: {
+      foo: [{ tag: 'script', attrs: { src: 'b.js' } }],
+    },
+  },
+};
+```
+
+编译后，可以看到页面 `foo` 注入标签：
+
+```html
+<script src="b.js"></script>
+```
+
+其他页面则注入了：
+
+```html
+<script src="a.js"></script>
+```
 
-<Main />

package/docs/zh/configure/app/html/tags.mdx

@@ -1,9 +1,20 @@
 ---
 title: tags
+configName: html.tags
 ---
 
 # html.tags
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/tags.md';
+- **类型：**
 
-<Main />
+```ts
+type TagsConfig = HtmlTag | HtmlTagHandler | Array<HtmlTag | HtmlTagHandler>;
+```
+
+- **默认值：** `undefined`
+
+添加和修改最终注入到 HTML 页面的标签。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/html/template-by-entries.mdx

@@ -4,6 +4,30 @@ title: templateByEntries
 
 # html.templateByEntries
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/templateByEntries.md';
+- **类型：** `Object`
+- **默认值：** `undefined`
+
+用于在多页面的场景下，为不同的页面设置不同的 HTML 模板。
+
+整体用法与 `template` 一致，并且可以使用「入口名称」作为 key ，对各个页面进行单独设置。
+
+`templateByEntries` 的优先级高于 `template`，因此会覆盖 `template` 设置的值。
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 `html.template` 的函数用法代替。
+:::
+
+### 示例
+
+```js
+export default {
+  html: {
+    template: './static/index.html',
+    templateByEntries: {
+      foo: './src/pages/foo/index.html',
+      bar: './src/pages/bar/index.html',
+    },
+  },
+};
+```
 
-<Main />

package/docs/zh/configure/app/html/template-parameters-by-entries.mdx

@@ -4,6 +4,33 @@ title: templateParametersByEntries
 
 # html.templateParametersByEntries
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/templateParametersByEntries.md';
+- **类型：** `Object`
+- **默认值：** `undefined`
+
+用于在多页面的场景下，为不同的页面设置不同的模板参数。
+
+整体用法与 `templateParameters` 一致，并且可以使用「入口名称」作为 key ，对各个页面进行单独设置。
+
+`templateParametersByEntries` 的优先级高于 `templateParameters`，因此会覆盖 `templateParameters` 中设置的值。
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 `html.templateParameters` 的函数用法代替。
+:::
+
+### 示例
+
+```js
+export default {
+  html: {
+    templateParametersByEntries: {
+      foo: {
+        type: 'a',
+      },
+      bar: {
+        type: 'b',
+      },
+    },
+  },
+};
+```
 
-<Main />

package/docs/zh/configure/app/html/template-parameters.mdx

@@ -1,9 +1,38 @@
 ---
 title: templateParameters
+configName: html.templateParameters
 ---
 
 # html.templateParameters
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/templateParameters.md';
+- **类型：** `Record<string, unknown> | Function`
+- **默认值：**
 
-<Main />
+```ts
+type DefaultParameters = {
+  mountId: string; // 对应 html.mountId 配置
+  entryName: string; // 入口名称
+  assetPrefix: string; // 对应 dev.assetPrefix 和 output.assetPrefix 配置
+  compilation: Compilation; // Rspack 的 compilation 对象
+  rspackConfig: Rspack.Configuration; // Rspack 的配置对象
+  // html-rspack-plugin 生成的参数
+  htmlPlugin: {
+    tags: {
+      headTags: HtmlTagObject[];
+      bodyTags: HtmlTagObject[];
+    };
+    files: {
+      publicPath: string;
+      js: Array<string>;
+      css: Array<string>;
+      favicon?: string;
+    };
+  };
+};
+```
+
+定义 HTML 模板中的参数，对应 [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin) 的 `templateParameters` 配置项。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/html/template.mdx

@@ -1,9 +1,15 @@
 ---
 title: template
+configName: html.template
 ---
 
 # html.template
 
-import Main from '@modern-js/builder-doc/docs/zh/config/html/template.md';
+- **类型：** `string | Function`
+- **默认值：**
 
-<Main />
+定义 HTML 模板的文件路径，可以是相对路径或绝对路径。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />