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

package/docs/zh/configure/app/output/assets-retry.mdx

@@ -4,6 +4,76 @@ title: assetsRetry
 
 # output.assetsRetry
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/assetsRetry.md';
+- **类型：** `Object`
 
-<Main />
+`output.assetsRetry` 用于配置资源加载失败时的重试逻辑。配置类型如下:
+
+```ts
+export type AssetsRetryHookContext = {
+  times: number;
+  domain: string;
+  url: string;
+  tagName: string;
+};
+
+export type AssetsRetryOptions = {
+  type?: string[];
+  domain?: string[];
+  max?: number;
+  test?: string | ((url: string) => boolean);
+  crossOrigin?: boolean | 'anonymous' | 'use-credentials';
+  inlineScript?: boolean;
+  onRetry?: (options: AssetsRetryHookContext) => void;
+  onSuccess?: (options: AssetsRetryHookContext) => void;
+  onFail?: (options: AssetsRetryHookContext) => void;
+};
+```
+
+- **默认值：** `undefined`
+
+由于该能力会往 HTML 中注入额外的一些运行时代码，因此我们默认关闭了该能力，如果需要开启该能力，你可以添加以下配置：
+
+```js
+export default {
+  output: {
+    assetsRetry: {},
+  },
+};
+```
+
+当你开启该能力后，`assetsRetry` 的默认配置如下：
+
+```ts
+export const defaultAssetsRetryOptions: AssetsRetryOptions = {
+  type: ['script', 'link', 'img'],
+  domain: [],
+  max: 3,
+  test: '',
+  crossOrigin: false,
+  onRetry: () => {},
+  onSuccess: () => {},
+  onFail: () => {},
+};
+```
+
+### 示例
+
+你可以通过 `assetsRetry` 配置项，来定制你的重试逻辑。
+
+如，通过 `assetsRetry.domain` 指定资源加载失败时的重试域名列表：
+
+```js
+export default {
+  output: {
+    assetsRetry: {
+      domain: ['https://cdn1.com', 'https://cdn2.com', 'https://cdn3.com'],
+    },
+  },
+};
+```
+
+添加以上配置后，当 `cdn1.com` 域名的资源加载失败时，请求域名会自动降级到 `cdn2.com`。
+
+如果 `cdn2.com` 的资源也请求失败，则会继续请求 `cdn3.com`。
+
+`assetsRetry` 是基于 Rsbuild 的 Assets Retry 插件实现的，并提供相同的配置项。你可以参考 [Rsbuild - Assets Retry 插件](https://rsbuild.dev/zh/plugins/list/plugin-assets-retry#%E9%80%89%E9%A1%B9) 来了解所有可用的配置项。

package/docs/zh/configure/app/output/charset.mdx

@@ -1,9 +1,15 @@
 ---
 title: charset
+configName: output.charset
 ---
 
 # output.charset
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/charset.md';
+- **类型：** `'ascii' | 'utf8'`
+- **默认值：** `'ascii'`
 
-<Main />
+`charset` 配置项允许你指定输出文件的[字符编码](https://developer.mozilla.org/en-US/docs/Glossary/Character_encoding) 字符编码，以确保它们在不同的环境中能够正确显示。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/output/clean-dist-path.mdx

@@ -4,6 +4,17 @@ title: cleanDistPath
 
 # output.cleanDistPath
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/cleanDistPath.md';
+- **类型：** `boolean`
+- **默认值：** `true`
 
-<Main />
+是否在构建开始前清理 dist 目录下的所有文件。
+
+默认情况下，Modern.js 会自动清理 dist 目录下的文件，你可以把 `cleanDistPath` 设置为 `false` 来禁用该行为。
+
+```ts
+export default {
+  output: {
+    cleanDistPath: false,
+  },
+};
+```

package/docs/zh/configure/app/output/convert-to-rem.mdx

@@ -4,6 +4,81 @@ title: convertToRem
 
 # output.convertToRem
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/convertToRem.md';
+- **类型：** `boolean | object`
+- **默认值：** `false`
+
+通过设置 `output.convertToRem`，Modern.js 可进行如下处理：
+
+- 将 CSS 中的 px 转成 rem
+- 在 HTML 模版中插入运行时代码，对根元素 fontSize 进行设置
+
+### Boolean 类型
+
+当设置 `output.convertToRem` 为 `true`，将开启 rem 处理能力。
+
+```js
+export default {
+  output: {
+    convertToRem: true,
+  },
+};
+```
+
+此时，rem 配置默认如下：
+
+```js
+{
+  enableRuntime: true,
+  rootFontSize: 50,
+  screenWidth: 375,
+  rootFontSize: 50,
+  maxRootFontSize: 64,
+  widthQueryKey: '',
+  excludeEntries: [],
+  supportLandscape: false,
+  useRootFontSizeBeyondMax: false,
+  pxtorem: {
+    rootValue: 50,
+    unitPrecision: 5,
+    propList: ['*'],
+  }
+}
+```
+
+### Object 类型
+
+当 `output.convertToRem` 的值为 `object` 类型时，Modern.js 会根据当前配置进行 rem 处理。
+
+选项：
+
+| 名称                     | 类型       | 默认值                                                                                                                                  | 描述                                                                                                                                          |
+| ------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| enableRuntime            | `boolean`  | `true`                                                                                                                                  | 是否自动生成 runtime 代码来动态计算根元素字体大小                                                                                             |
+| inlineRuntime            | `boolean`  | `true`                                                                                                                                  | 是否将 runtime 代码内联到 HTML 文件中。如果设置为 `false`，运行时代码会被抽取为一个独立的 `convert-rem.[version].js` 文件，并输出到产物目录下 |
+| rootFontSize             | `number`   | `50`                                                                                                                                    | 根元素字体值                                                                                                                                  |
+| maxRootFontSize          | `number`   | `64`                                                                                                                                    | 最大根元素字体值                                                                                                                              |
+| widthQueryKey            | `string`   | `'' `                                                                                                                                   | 根据 widthQueryKey 的值去 url query 中取 client width                                                                                         |
+| screenWidth              | `number`   | `375`                                                                                                                                   | UI 设计图宽度                                                                                                                                 |
+| excludeEntries           | `string[]` | `[]`                                                                                                                                    | 设置不注入 runtime 代码的页面入口，通常需要配合 `pxtorem.exclude` 使用                                                                        |
+| supportLandscape         | `boolean`  | `false`                                                                                                                                 | 横屏时使用 height 计算 rem                                                                                                                    |
+| useRootFontSizeBeyondMax | `boolean`  | `false`                                                                                                                                 | 超过 maxRootFontSize 时，是否使用 rootFontSize                                                                                                |
+| pxtorem                  | `object`   | <ul><li>rootValue。默认与 rootFontSize 相同 </li><li>unitPrecision: 5。精确位数 </li><li>propList: ['*']。支持转换的 CSS 属性</li></ul> | [postcss-pxtorem](https://github.com/cuth/postcss-pxtorem#options) 插件属性                                                                   |
+
+### 示例
+
+```js
+export default {
+  output: {
+    convertToRem: {
+      rootFontSize: 30,
+      excludeEntries: ['404', 'page2'],
+      pxtorem: {
+        propList: ['font-size'],
+      },
+    },
+  },
+};
+```
+
+详细用法可参考 [rsbuild-plugin-rem](https://github.com/rspack-contrib/rsbuild-plugin-rem)。
 
-<Main />

package/docs/zh/configure/app/output/copy.mdx

@@ -4,6 +4,10 @@ title: copy
 
 # output.copy
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/copy.md';
+- **类型：** `Rspack.CopyRspackPluginOptions | Rspack.CopyRspackPluginOptions['patterns']`
+- **默认值：** `undefined`
 
-<Main />
+
+将指定的文件或目录拷贝到构建输出目录中，基于 [rspack.CopyRspackPlugin](https://rspack.dev/zh/plugins/rspack/copy-rspack-plugin) 实现。
+
+更详细的配置项请参考：[rspack.CopyRspackPlugin](https://rspack.dev/zh/plugins/rspack/copy-rspack-plugin)文档。

package/docs/zh/configure/app/output/css-module-local-ident-name.mdx

@@ -4,6 +4,18 @@ title: cssModuleLocalIdentName
 
 # output.cssModuleLocalIdentName
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/cssModuleLocalIdentName.md';
+- **类型：** `string`
+- **默认值：**
 
-<Main />
+```ts
+// isProd 表示生产环境构建
+const localIdentName = isProd
+  ? '[local]-[hash:base64:6]'
+  : '[path][name]__[local]-[hash:base64:6]';
+```
+
+设置 CSS Modules 编译后生成的 className 格式。
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 `output.cssModules.localIdentName` 的代替。
+:::

package/docs/zh/configure/app/output/css-modules.mdx

@@ -1,9 +1,53 @@
 ---
 title: cssModules
+configName: output.cssModules
 ---
 
 # output.cssModules
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/cssModules.md';
+- **类型：**
 
-<Main />
+```ts
+type CssModules = {
+  auto?:
+    | boolean
+    | RegExp
+    | ((
+        resourcePath: string,
+        resourceQuery: string,
+        resourceFragment: string,
+      ) => boolean);
+  exportLocalsConvention?:
+    | 'asIs'
+    | 'camelCase'
+    | 'camelCaseOnly'
+    | 'dashes'
+    | 'dashesOnly';
+  exportGlobals?: boolean;
+  localIdentName?: string;
+  mode?:
+    | 'local'
+    | 'global'
+    | 'pure'
+    | 'icss'
+    | ((resourcePath: string) => 'local' | 'global' | 'pure' | 'icss');
+  namedExport?: boolean;
+};
+```
+
+- **默认值：**
+
+```ts
+const defaultCssModules = {
+  auto: true,
+  namedExport: false,
+  exportGlobals: false,
+  exportLocalsConvention: 'camelCase',
+};
+```
+
+自定义 CSS 模块配置。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/output/data-uri-limit.mdx

@@ -1,9 +1,31 @@
 ---
 title: dataUriLimit
+configName: output.dataUriLimit
 ---
 
 # output.dataUriLimit
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/dataUriLimit.md';
+- **类型：**
 
-<Main />
+```ts
+type DataUriLimitConfig =
+  | number
+  | {
+      svg?: number;
+      font?: number;
+      image?: number;
+      media?: number;
+    };
+```
+
+- **默认值：**
+
+```js
+const defaultDatUriLimit = 10000;
+```
+
+设置图片、字体、媒体等静态资源被自动内联为 base64 的体积阈值。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/output/disable-css-extract.mdx

@@ -4,6 +4,13 @@ title: disableCssExtract
 
 # output.disableCssExtract
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/disableCssExtract.md';
+- **类型：** `boolean`
+- **默认值：** `false`
 
-<Main />
+是否禁用 CSS 提取逻辑，并将 CSS 文件内联到 JS 文件中。
+
+默认情况下，Modern.js 会把 CSS 提取为独立的 `.css` 文件，并输出到构建产物目录。设置该选项为 `true` 后，CSS 文件会被内联到 JS 文件中，并在运行时通过 `<style>` 标签插入到页面上。
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 `output.injectStyles` 的代替。
+:::

package/docs/zh/configure/app/output/disable-css-module-extension.mdx

@@ -4,6 +4,56 @@ title: disableCssModuleExtension
 
 # output.disableCssModuleExtension
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/disableCssModuleExtension.md';
+- **类型：** `boolean`
+- **默认值：** `false`
 
-<Main />
+是否将源码目录下的所有样式文件当做 CSS Modules 模块进行处理。
+
+在默认情况下，只有 `*.module.css` 结尾的文件才被视为 CSS Modules 模块。开启该配置项之后，会将源码目录下的所有 `*.css` 样式文件当做 CSS Modules 模块。
+
+`.sass`、`.scss` 和 `.less` 文件的处理规则与 `.css` 文件一致，也会受到 `disableCssModuleExtension` 的影响。
+
+:::tip
+我们不推荐开启此配置项，因为开启 `disableCssModuleExtension` 后，CSS Modules 文件和普通 CSS 文件无法得到明确的区分，不利于长期维护。
+:::
+
+### 示例
+
+```js
+export default {
+  output: {
+    disableCssModuleExtension: true,
+  },
+};
+```
+
+### 规则
+
+以下是对 CSS Modules 判断规则的详细解释：
+
+#### 未开启 disableCssModuleExtension（默认）
+
+以下文件会视为 CSS Modules：
+
+- 所有 `*.module.css` 文件
+
+以下文件会视为普通 CSS：
+
+- 所有 `*.css` 文件（不含 `.module`）
+- 所有 `*.global.css` 文件
+
+#### 开启 disableCssModuleExtension
+
+以下文件会视为 CSS Modules：
+
+- 源码目录下的 `*.css` 和 `*.module.css` 文件
+- node_modules 下的 `*.module.css` 文件
+
+以下文件会视为普通 CSS：
+
+- 所有 `*.global.css` 文件
+- node_modules 下的 `*.css` 文件（不含 `.module`）
+
+:::tip
+对于 node_modules 中的 CSS Modules 文件，请始终使用 `*.module.css` 后缀。
+:::

package/docs/zh/configure/app/output/disable-filename-hash.mdx

@@ -4,6 +4,13 @@ title: disableFilenameHash
 
 # output.disableFilenameHash
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/disableFilenameHash.md';
+- **类型：** `boolean`
+- **默认值：** `false`
 
-<Main />
+移除生产环境的构建产物名称中的 hash 值。
+
+在生产环境构建后，会自动在文件名中间添加 hash 值，如果不需要添加，可以通过 `output.disableFilenameHash` 配置来禁用该行为。
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 `output.filenameHash` 的布尔用法代替。
+:::

package/docs/zh/configure/app/output/disable-inline-runtime-chunk.mdx

@@ -4,6 +4,42 @@ title: disableInlineRuntimeChunk
 
 # output.disableInlineRuntimeChunk
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/disableInlineRuntimeChunk.md';
+- **类型：** `boolean`
+- **默认值：** `false`
 
-<Main />
+用于控制是否将打包工具的 runtime 代码内联到 HTML 中。
+
+:::tip 什么是 runtimeChunk
+当构建完成后，会在 dist 目录生成 `builder-runtime.js` 文件，该文件为 webpack 或 Rspack 的 runtime 代码，即 runtimeChunk。
+
+runtimeChunk 是一段运行时代码，它由 webpack 或 Rspack 提供，包含必要的模块处理逻辑，比如模块加载、模块解析等，具体可参考 [Runtime](https://webpack.js.org/concepts/manifest/#runtime)。
+
+:::
+
+在生产环境下，Modern.js 默认会将 runtimeChunk 文件内联到 HTML 文件中，而不是写到产物目录中，这样做是为了减少文件请求的数量。
+
+### 禁用内联
+
+如果你不希望 runtimeChunk 文件被内联到 HTML 文件里，可以把 `disableInlineRuntimeChunk` 设置为 `true`，此时会生成一个独立的 `builder-runtime.js` 文件。
+
+```js
+export default {
+  output: {
+    disableInlineRuntimeChunk: true,
+  },
+};
+```
+
+### 合并到页面文件中
+
+如果你不希望生成独立的 runtimeChunk 文件，而是想让 runtimeChunk 代码被打包到页面的 JS 文件里，可以这样设置：
+
+```js
+export default {
+  tools: {
+    bundlerChain(chain) {
+      chain.optimization.runtimeChunk(false);
+    },
+  },
+};
+```

package/docs/zh/configure/app/output/disable-minimize.mdx

@@ -4,6 +4,11 @@ title: disableMinimize
 
 # output.disableMinimize
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/disableMinimize.md';
+- **类型：** `boolean`
+- **默认值：** `false`
 
-<Main />
+是否禁用生产环境下的代码压缩。
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 `output.minify` 的布尔用法代替。
+:::

package/docs/zh/configure/app/output/disable-source-map.mdx

@@ -4,6 +4,28 @@ title: disableSourceMap
 
 # output.disableSourceMap
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/disableSourceMap.md';
+- **类型：**
 
-<Main />
+```ts
+type DisableSourceMap =
+  | boolean
+  | {
+      js?: boolean;
+      css?: boolean;
+    };
+```
+
+- **默认值：**
+
+```ts
+const defaultDisableSourceMap = {
+  js: false,
+  css: process.env.NODE_ENV === 'production',
+};
+```
+
+是否禁用 Source Map 生成。
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 `output.sourceMap` 的布尔用法代替。
+:::

package/docs/zh/configure/app/output/disable-svgr.mdx

@@ -4,6 +4,18 @@ title: disableSvgr
 
 # output.disableSvgr
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/disableSvgr.md';
+- **类型：** `boolean`
+- **默认值：** `false`
 
-<Main />
+是否调用 SVGR 将 SVG 转化为 React 组件。如果设置为 true，将把所有的.svg 文件视为资源处理。
+
+默认情况下，在 JS 文件中引用 SVG 资源时，Modern.js 会调用 SVGR，将 SVG 图片转换为一个 React 组件。
+如果你确定项目内的所有 SVG 资源都没有当成 React 组件使用时，可以通过将 `disableSvgr` 设置为 true 来关闭此项转换，以提升构建性能。
+
+```js
+export default {
+  output: {
+    disableSvgr: true,
+  },
+};
+```

package/docs/zh/configure/app/output/disable-ts-checker.mdx

@@ -4,6 +4,50 @@ title: disableTsChecker
 
 # output.disableTsChecker
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/disableTsChecker.md';
+- **类型：** `boolean`
+- **默认值：** `false`
 
-<Main />
+是否禁用编译过程中的 TypeScript 类型检查。
+
+默认情况下，Modern.js 执行构建的过程中，会在一个独立的进程里运行 TypeScript 类型检查工具，它的检查逻辑与 TypeScript 原生的 `tsc` 命令一致，你可以通过 `tsconfig.json` 或 `tools.tsChecker` 配置项来自定义检查行为。
+
+### 阻塞编译
+
+- 在开发环境构建时，类型错误不会阻塞编译流程。
+- 在生产环境构建时，类型错误会导致构建失败，以保证生产环境代码的稳定性。
+
+### 示例
+
+禁用 TypeScript 类型检查：
+
+```js
+export default {
+  output: {
+    disableTsChecker: true,
+  },
+};
+```
+
+禁用开发环境构建时的类型检查：
+
+```js
+export default {
+  output: {
+    disableTsChecker: process.env.NODE_ENV === 'development',
+  },
+};
+```
+
+禁用生产环境构建时的类型检查：
+
+```js
+export default {
+  output: {
+    disableTsChecker: process.env.NODE_ENV === 'production',
+  },
+};
+```
+
+:::tip
+不建议在生产环境构建时禁用类型检查，这会导致线上代码的稳定性下降，请谨慎使用。
+:::

package/docs/zh/configure/app/output/dist-path.mdx

@@ -1,9 +1,46 @@
 ---
 title: distPath
+configName: output.distPath
 ---
 
 # output.distPath
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/distPath.md';
+- **类型：**
 
-<Main />
+```ts
+type DistPathConfig = {
+  root?: string;
+  html?: string;
+  js?: string;
+  css?: string;
+  svg?: string;
+  font?: string;
+  wasm?: string;
+  image?: string;
+  media?: string;
+  server?: string;
+  worker?: string;
+};
+```
+
+- **默认值：**
+
+```js
+const defaultDistPath = {
+  root: 'dist',
+  css: 'static/css',
+  svg: 'static/svg',
+  font: 'static/font',
+  html: 'html',
+  wasm: 'static/wasm',
+  image: 'static/image',
+  media: 'static/media',
+  js: 'static/js',
+};
+```
+
+设置构建产物的输出目录，Modern.js 会根据产物的类型输出到对应的子目录下。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/zh/configure/app/output/enable-asset-fallback.mdx

@@ -4,6 +4,33 @@ title: enableAssetFallback
 
 # output.enableAssetFallback
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/enableAssetFallback.md';
+- **类型：** `boolean`
+- **默认值：** `false`
 
-<Main />
+开启该选项后，当编译过程中遇到无法识别的文件类型时，会直接将该文件直接输出到产物目录；否则会抛出一个异常。
+
+### 示例
+
+开启配置项：
+
+```js
+export default {
+  output: {
+    enableAssetFallback: true,
+  },
+};
+```
+
+在代码中引用一个未知类型的模块：
+
+```js
+import './foo.xxx';
+```
+
+编译后，`foo.xxx` 会被自动输出到 `dist/static/media` 目录下。
+
+你可以通过 `output.distPath.media` 和 `output.filename.media` 配置项来控制 fallback 后的输出路径和文件名称。
+
+:::tip
+开启该配置会导致 webpack 配置中的 rules 结构变化，增加一层额外的 `oneOf` 嵌套结构。大多数情况下，我们不推荐你使用此配置。
+:::