@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

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

@@ -0,0 +1,20 @@
+---
+title: cleanDistPath
+---
+
+# output.cleanDistPath
+
+- **类型：** `boolean`
+- **默认值：** `true`
+
+是否在构建开始前清理 dist 目录下的所有文件。
+
+默认情况下，Modern.js 会自动清理 dist 目录下的文件，你可以把 `cleanDistPath` 设置为 `false` 来禁用该行为。
+
+```ts
+export default {
+  output: {
+    cleanDistPath: false,
+  },
+};
+```

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

@@ -0,0 +1,84 @@
+---
+title: convertToRem
+---
+
+# output.convertToRem
+
+- **类型：** `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)。
+

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

@@ -0,0 +1,14 @@
+---
+title: copy
+---
+
+# output.copy
+
+- **类型：** `Rspack.CopyRspackPluginOptions | Rspack.CopyRspackPluginOptions['patterns']`
+- **默认值：** `undefined`
+
+将指定的文件或目录拷贝到构建输出目录中，基于 [rspack.CopyRspackPlugin](https://rspack.rs/zh/plugins/rspack/copy-rspack-plugin) 实现。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="output.copy" />

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

@@ -0,0 +1,52 @@
+---
+title: cssModules
+---
+
+# output.cssModules
+
+- **类型：**
+
+```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 RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="output.cssModules" />

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

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

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

@@ -0,0 +1,59 @@
+---
+title: disableCssModuleExtension
+---
+
+# output.disableCssModuleExtension
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+是否将源码目录下的所有样式文件当做 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-inline-runtime-chunk.mdx

@@ -0,0 +1,45 @@
+---
+title: disableInlineRuntimeChunk
+---
+
+# output.disableInlineRuntimeChunk
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+用于控制是否将打包工具的 runtime 代码内联到 HTML 中。
+
+:::tip 什么是 runtimeChunk
+当构建完成后，会在 dist 目录生成 `builder-runtime.js` 文件，该文件为 Rspack 的 runtime 代码，即 runtimeChunk。
+
+runtimeChunk 是一段运行时代码，它由 Rspack 提供，包含必要的模块处理逻辑，比如模块加载、模块解析等，具体可参考 [Runtime Chunk](https://rspack.rs/config/optimization#optimizationruntimechunk)。
+
+:::
+
+在生产环境下，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-svgr.mdx

@@ -0,0 +1,21 @@
+---
+title: disableSvgr
+---
+
+# output.disableSvgr
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+是否调用 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

@@ -0,0 +1,53 @@
+---
+title: disableTsChecker
+---
+
+# output.disableTsChecker
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+是否禁用编译过程中的 TypeScript 类型检查。
+
+默认情况下，Modern.js 执行构建的过程中，会在一个独立的进程里运行 TypeScript 类型检查工具，它的检查逻辑与 TS-Go native preview 工具链一致，你可以通过 `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

@@ -0,0 +1,50 @@
+---
+title: distPath
+---
+
+# output.distPath
+
+import CommentTips from '@site-docs/components/output-distpath-warning';
+
+<CommentTips />
+
+- **类型：**
+
+```ts
+type DistPathConfig = {
+  root?: string;
+  html?: string;
+  js?: string;
+  css?: string;
+  svg?: string;
+  font?: string;
+  wasm?: string;
+  image?: string;
+  media?: string;
+  worker?: string;
+  assets?: 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',
+  assets: 'static/assets',
+};
+```
+
+设置构建产物的输出目录，Modern.js 会根据产物的类型输出到对应的子目录下。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="output.distPath" />

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

@@ -0,0 +1,40 @@
+---
+title: enableAssetManifest
+---
+
+# output.enableAssetManifest
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+是否生成 manifest 文件，该文件包含所有构建产物的信息。
+
+### 示例
+
+添加以下配置来开启：
+
+```js
+export default {
+  output: {
+    enableAssetManifest: true,
+  },
+};
+```
+
+开启后，当编译完成时，会自动生成 `dist/asset-manifest.json` 文件：
+
+```json
+{
+  "files": {
+    "main.css": "/static/css/main.45b01211.css",
+    "main.js": "/static/js/main.52fd298f.js",
+    "html/main/index.html": "/html/main/index.html"
+  },
+  "entrypoints": ["static/css/main.45b01211.css", "static/js/main.52fd298f.js"]
+}
+```
+
+如果当前项目有多种类型构建产物，比如包含了 SSR 构建产物，那么会生成多份 manifest.json 文件。
+
+- web 产物：`asset-manifest.json`
+- node 产物：`asset-manifest-node.json`

package/docs/zh/configure/app/output/enable-css-module-tsdeclaration.mdx

@@ -0,0 +1,32 @@
+---
+title: enableCssModuleTSDeclaration
+---
+
+# output.enableCssModuleTSDeclaration
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+是否生成 CSS Modules 的 TypeScript 声明文件。
+
+### Example
+
+启用 CSS Module TypeScript 声明，比如：
+
+```js
+export default {
+  output: {
+    enableCssModuleTSDeclaration: true,
+  },
+};
+```
+
+项目构建完成后，每个 CSS Module 文件都会生成一个 `.d.ts` 文件。例如：
+
+```ts
+interface CssExports {
+  title: string;
+}
+export const cssExports: CssExports;
+export default cssExports;
+```

package/docs/zh/configure/app/output/enable-inline-route-manifests.mdx

@@ -0,0 +1,21 @@
+---
+title: disableInlineRouteManifests
+---
+
+# output.disableInlineRouteManifests
+
+- **类型:** `boolean`
+- **默认值:** `false`
+
+当使用约定式路由时，框架为了做一些优化，会向客户端中注入路由信息，默认情况下路由信息会注入到 html 中，
+当该配置为 `true` 时，路由信息会注入到一个单独的 JS 文件中。
+
+Example:
+
+```ts
+export default {
+  output: {
+    disableInlineRouteManifests: true,
+  },
+};
+```

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

@@ -0,0 +1,24 @@
+---
+title: externals
+---
+
+# output.externals
+
+- **类型:**
+
+```ts
+type Externals =
+  | string
+  | object
+  | function
+  | RegExp
+  | Array<string | object | function | RegExp>;
+```
+
+- **默认值:** `undefined`
+
+在构建时，防止将代码中某些 `import` 的依赖包打包到 bundle 中，而是在运行时再去从外部获取这些依赖。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="output.externals" />

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

@@ -0,0 +1,14 @@
+---
+title: filenameHash
+---
+
+# output.filenameHash
+
+- **类型：** `boolean | string`
+- **默认值：** `true`
+
+在生产模式构建后，是否在产物的文件名中添加 hash 值。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="output.filenameHash" />

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

@@ -0,0 +1,62 @@
+---
+title: filename
+---
+
+# output.filename
+
+:::warning
+
+在 Modern.js 开发阶段，或是使用 Modern.js 服务器部署应用时，应避免使用该配置修改 html 产物文件名，会导致页面 404。
+
+:::
+
+- **类型：**
+
+```ts
+type FilenameConfig = {
+  html?: string;
+  js?:
+    | string
+    | ((pathData: Rspack.PathData, assetInfo: Rspack.JsAssetInfo) => string);
+  css?: string;
+  svg?: string;
+  font?: string;
+  image?: string;
+  media?: string;
+  assets?: string;
+};
+```
+
+- **默认值：**
+
+```js
+// 开发模式构建
+const devDefaultFilename = {
+  html: '[name].html',
+  js: '[name].js',
+  css: '[name].css',
+  svg: '[name].[contenthash:8].svg',
+  font: '[name].[contenthash:8][ext]',
+  image: '[name].[contenthash:8][ext]',
+  media: '[name].[contenthash:8][ext]',
+  assets: '[name].[contenthash:8][ext]',
+};
+
+// 生产模式构建
+const prodDefaultFilename = {
+  html: '[name].html',
+  js: output.target === 'node' ? '[name].js' : '[name].[contenthash:8].js',
+  css: '[name].[contenthash:8].css',
+  svg: '[name].[contenthash:8].svg',
+  font: '[name].[contenthash:8][ext]',
+  image: '[name].[contenthash:8][ext]',
+  media: '[name].[contenthash:8][ext]',
+  assets: '[name].[contenthash:8][ext]',
+};
+```
+
+设置构建产物的名称。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="output.filename" />

package/docs/zh/configure/app/output/inject-styles.mdx

@@ -0,0 +1,14 @@
+---
+title: injectStyles
+---
+
+# output.injectStyles
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+是否将 CSS 样式插入到 DOM 中。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="output.injectStyles" />

package/docs/zh/configure/app/output/inline-scripts.mdx

@@ -0,0 +1,33 @@
+---
+title: inlineScripts
+---
+
+# output.inlineScripts
+
+- **类型：**
+
+```ts
+type InlineScriptsTest =
+  | RegExp
+  | ((params: { size: number; name: string }) => boolean);
+
+type InlineScripts =
+  | boolean
+  | InlineScriptsTest
+  | {
+      enable?: boolean | 'auto';
+      test: InlineScriptsTest;
+    };
+```
+
+- **默认值：** `/builder-runtime([.].+)?\.js$/`
+
+用来控制是否用 `<script>` 标签将产物中的 script 文件（.js 文件）inline 到 HTML 中。
+
+:::tip
+当使用约定式路由时，如果开启了这个选项，需要将 [output.splitRouteChunks](/configure/app/output/split-route-chunks) 设置为 false。
+:::
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="output.inlineScripts" />