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

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

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

package/docs/zh/configure/app/output/legal-comments.mdx

@@ -0,0 +1,22 @@
+---
+title: legalComments
+---
+
+# output.legalComments
+
+- **类型：** `'linked' | 'inline' | 'none'`
+- **默认值：** `'linked'`
+
+配置 legal comment 的处理方式。
+
+legal comment 是 JS 或 CSS 文件中的一些特殊注释，这些注释包含 `@license` 或 `@preserve`，或是以 `//!` 或 `/*!` 开头。默认情况下，这些注释保留在输出文件中，因为这遵循了代码原作者的意图。
+
+你可以通过 `legalComments` 来配置相关行为：
+
+- `linked`：将所有 legal comments 移至 .LEGAL.txt 文件并通过注释链接到它们。
+- `inline`：保留所有 legal comments。
+- `none`：移除所有 legal comments。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="output.legalComments" />

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

@@ -0,0 +1,26 @@
+---
+title: minify
+---
+
+# output.minify
+
+- **类型:**
+
+```ts
+type Minify =
+  | boolean
+  | {
+      js?: boolean;
+      jsOptions?: SwcJsMinimizerRspackPluginOptions;
+      css?: boolean;
+      cssOptions?: LightningCssMinimizerRspackPluginOptions;
+    };
+```
+
+- **默认值:** `true`
+
+用于设置是否在生产模式下开启代码压缩，或是配置压缩工具的选项。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="output.minify" />

package/docs/zh/configure/app/output/override-browserslist.mdx

@@ -0,0 +1,26 @@
+---
+title: overrideBrowserslist
+---
+
+# output.overrideBrowserslist
+
+- **类型：** `string[] | undefined`
+- **默认值：**
+
+```ts
+const defaultBrowserListMap: Record<RsbuildTarget, string[]> = {
+  web: ['chrome >= 87', 'edge >= 88', 'firefox >= 78', 'safari >= 14'],
+  node: ['node >= 14'],
+  'web-worker': ['chrome >= 87', 'edge >= 88', 'firefox >= 78', 'safari >= 14'],
+};
+```
+
+指定项目兼容的目标浏览器范围。
+
+该值会被 [SWC](https://github.com/swc-project/swc) 和 [autoprefixer](https://github.com/postcss/autoprefixer) 用来确定需要转换的 JavaScript 语法特性和需要添加的 CSS 浏览器前缀。
+
+其他配置方式和配置优先级请参考 [Browserslist 配置](/guides/advanced-features/compatibility.html)。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="output.overrideBrowserslist" />

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

@@ -0,0 +1,18 @@
+---
+title: polyfill
+---
+
+# output.polyfill
+
+- **类型：** `'entry' | 'usage' | 'ua' | 'off'`
+- **默认值：** `'entry'`
+
+通过 `output.polyfill` 你可以配置 Polyfill 的注入方式。
+
+import OutputPolyfillExtend from '@site-docs/components/output-polyfill-extend';
+
+<OutputPolyfillExtend />
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="output.polyfill" />

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

@@ -0,0 +1,38 @@
+---
+title: sourceMap
+---
+
+# output.sourceMap
+
+- **类型：**
+
+```ts
+type SourceMap =
+  | boolean
+  | {
+      js?: Rspack.Configuration['devtool'];
+      css?: boolean;
+    };
+```
+
+用于设置是否生成 source map 文件，以及生成哪一种格式的 source map。
+
+- **默认值：**
+
+```ts
+const defaultSourceMap = {
+  js: isDev ? 'cheap-module-source-map' : 'hidden-source-map',
+  css: isDev,
+};
+```
+
+在不配置 `output.sourceMap` 时，Modern.js 的 source map 生成规则与 Rsbuild 配置有差异：
+
+- 在开发模式构建时，会生成 JS 文件和 CSS 的 source map，便于进行开发调试。
+- 在生产模式构建时，会生成 JS 的 source map 用于堆栈回溯，不生成 CSS 文件的 source map，以提供最佳的构建性能。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="output.sourceMap" />
+
+

package/docs/zh/configure/app/output/split-route-chunks.mdx

@@ -0,0 +1,20 @@
+---
+title: splitRouteChunks
+---
+
+# output.splitRouteChunks
+
+- **类型：** `boolean`
+- **默认值：** `true`
+
+当使用约定式路由时，框架会根据路由对 js 和 css 进行拆分，以实现按需加载。如果你的项目不希望根据路由对 js 和 css 进行拆分，可以将该选项设置为 `false`。
+
+示例
+
+```ts
+export default {
+  output: {
+    splitRouteChunks: false,
+  },
+}
+```

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

@@ -0,0 +1,84 @@
+---
+title: ssg
+---
+
+# output.ssg
+
+- **类型：** `boolean | object`
+- **默认值：** `undefined`
+
+开启应用 SSG 功能的配置
+
+:::tip 开启 SSG 功能
+此配置需要在开启 SSG 功能情况下才会生效。请阅读 [静态站点生成](/guides/basic-features/render/ssg) 文档了解如何开启 SSG 功能及使用场景。
+
+:::
+
+:::info 前置阅读
+SSG 功能使用与路由关联性较大，建议使用前先了解[路由方案](/guides/basic-features/routes/routes)。
+
+:::
+
+:::info
+- 单入口建议使用 `output.ssg`。
+- 多入口建议优先使用 `output.ssgByEntries`。
+- 当 `output.ssg` 为 `true` 且未配置 `output.ssgByEntries` 时，所有入口下的所有路由都会作为 SSG 路由处理。
+
+:::
+
+## Boolean 类型
+
+当该配置设置为 `true` 时，将会默认开启所有入口的 SSG 功能。对**自控式路由**而言，将会渲染入口的根路由。对**约定式路由**而言，将会渲染入口中每一条路由。
+
+```js
+export default defineConfig({
+  output: {
+    ssg: true,
+  },
+});
+```
+
+## Object 类型
+
+当值类型为 `Object` 时，可以配置如下属性。
+
+### 配置类型
+
+```ts
+type SSGRouteOptions =
+  | string
+  | {
+      url: string;
+      headers?: Record<string, any>;
+    };
+
+type SSGOptions = {
+  headers?: Record<string, any>;
+  routes?: SSGRouteOptions[];
+};
+```
+
+### 示例
+
+下面的示例配置中，SSG 会渲染 `/`、`/about` 和 `/user/:id` 三条路由对应的页面。
+
+对于 `/user/:id` 路由，会在请求头中添加 `cookies`，并指定具体的路径。
+
+```ts title="modern.config.ts（单入口）"
+export default defineConfig({
+  output: {
+    ssg: {
+      routes: [
+        '/',
+        '/about',
+        {
+          url: '/user/modernjs',
+          headers: {
+            cookies: 'name=modernjs',
+          },
+        },
+      ],
+    },
+  },
+});
+```

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

@@ -0,0 +1,94 @@
+---
+title: ssgByEntries
+---
+
+# output.ssgByEntries
+
+- **类型：** `Record<string, boolean | object>`
+- **默认值：** `undefined`
+
+在多入口应用中，为每个入口分别配置 SSG。
+
+:::info
+- 单入口建议使用 `output.ssg`。
+- 多入口建议优先使用 `output.ssgByEntries`。
+- 当 `output.ssg` 为 `true` 且未配置 `output.ssgByEntries` 时，所有入口下的所有路由都会作为 SSG 路由处理。
+
+:::
+
+
+## 配置类型
+
+```ts
+type SSGRouteOptions =
+  | string
+  | {
+      url: string;
+      headers?: Record<string, any>;
+    };
+
+type SSGOptions = {
+  headers?: Record<string, any>;
+  routes?: SSGRouteOptions[];
+};
+
+// ssgByEntries 类型
+type SSGMultiEntryOptions = Record<string, boolean | SSGOptions>;
+```
+
+## 示例
+
+### 按入口启用/禁用 SSG
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  output: {
+    ssgByEntries: {
+      home: true,
+      admin: false,
+    },
+  },
+});
+```
+
+### 按入口配置具体路由
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  output: {
+    ssgByEntries: {
+      home: {
+        routes: ['/', '/about', '/user/modernjs'],
+      },
+      admin: {
+        routes: ['/', '/dashboard'],
+      },
+    },
+  },
+});
+```
+
+### 配置入口或路由请求头
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  output: {
+    ssgByEntries: {
+      home: {
+        headers: {
+          'x-tt-env': 'ppe_modernjs',
+        },
+        routes: [
+          '/',
+          {
+            url: '/about',
+            headers: {
+              from: 'modern-website',
+            },
+          },
+        ],
+      },
+    },
+  },
+});
+```

package/docs/zh/configure/app/output/svg-default-export.mdx

@@ -0,0 +1,34 @@
+---
+title: svgDefaultExport
+---
+
+# output.svgDefaultExport
+
+- **类型：** `'url' | 'component'`
+- **默认值：** `'url'`
+
+`output.svgDefaultExport` 可以用来配置 SVG 文件的默认导出。
+
+当 `output.svgDefaultExport` 配置为 `url` 时，SVG 文件的默认导出是文件的 URL。例如：
+
+```js
+import logo from './logo.svg';
+
+console.log(logo); // => 资源 url
+```
+
+当 `output.svgDefaultExport` 配置为 `component` 时，SVG 文件的默认导出是文件的 React 组件。例如：
+
+```js
+import Logo from './logo.svg';
+
+console.log(Logo); // => React 组件
+```
+
+此时，你也可以通过指定 `?url` 的 query 来导入 url，比如：
+
+```js
+import logo from './logo.svg?url';
+
+console.log(logo); // => 资源 url
+```

package/docs/zh/configure/app/output/temp-dir.mdx

@@ -0,0 +1,22 @@
+---
+title: tempDir
+---
+
+# output.tempDir
+
+- **类型：** `string`
+- **默认值：** `''`
+
+项目开发或构建时，Modern.js 会生成真实的 Rspack 入口和 HTML 模板，并放在临时目录下。
+
+如果希望由多个配置同时启动某项目，可以通过该配置，将文件生成到不同的临时目录下，避免相互干扰。配置可以是相对路径或绝对路径，但应避免项目外的路径。
+
+示例
+
+```ts
+export default {
+  output: {
+    tempDir: path.join('node_modules', '.temp-dir'),
+  },
+};
+```

package/docs/zh/configure/app/performance/build-cache.mdx

@@ -0,0 +1,43 @@
+---
+title: buildCache
+---
+
+# performance.buildCache
+
+- **类型：**
+
+```ts
+type BuildCacheConfig =
+  | {
+      /**
+       * 用于设置缓存文件的输出目录
+       */
+      cacheDirectory?: string;
+      /**
+       * 根据 cacheDigest 内容设置不同的缓存名称
+       */
+      cacheDigest?: Array<string | undefined>;
+      /**
+       * 一个包含构建依赖的文件数组。
+       * Rspack 将使用其中每个文件的哈希值来判断持久化缓存是否失效。
+       */
+      buildDependencies?: string[];
+    }
+  | boolean;
+```
+
+控制 Modern.js 在构建过程中的缓存行为。
+
+在构建时，Modern.js 默认会开启构建缓存来提升二次构建的速度。如果不希望缓存，你可以将 `buildCache` 置为 `false` 将其禁用掉：
+
+```js
+export default {
+  performance: {
+    buildCache: false,
+  },
+};
+```
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="performance.buildCache" />

package/docs/zh/configure/app/performance/chunk-split.mdx

@@ -0,0 +1,44 @@
+---
+title: chunkSplit
+---
+
+# performance.chunkSplit
+
+- **类型：** `Object`
+- **默认值：** `{ strategy: 'split-by-experience' }`
+
+`performance.chunkSplit` 用于配置 Modern.js 的拆包策略。配置项的类型 `ChunkSplit` 如下:
+
+```ts
+type ForceSplitting = RegExp[] | Record<string, RegExp>;
+
+interface BaseChunkSplit {
+  strategy?:
+    | 'split-by-module'
+    | 'split-by-experience'
+    | 'all-in-one'
+    | 'single-vendor';
+  override?: SplitChunks;
+  forceSplitting?: ForceSplitting;
+}
+
+interface SplitBySize {
+  strategy?: 'split-by-size';
+  minSize?: number;
+  maxSize?: number;
+  override?: SplitChunks;
+  forceSplitting?: ForceSplitting;
+}
+
+interface SplitCustom {
+  strategy?: 'custom';
+  splitChunks?: SplitChunks;
+  forceSplitting?: ForceSplitting;
+}
+
+export type ChunkSplit = BaseChunkSplit | SplitBySize | SplitCustom;
+```
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="performance.chunkSplit" />

package/docs/zh/configure/app/performance/dns-prefetch.mdx

@@ -0,0 +1,19 @@
+---
+title: dnsPrefetch
+---
+
+# performance.dnsPrefetch
+
+- **类型：** `undefined | string[]`
+
+- **默认值：** `undefined`
+
+为哪些资源配置 [dns-prefetch](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/dns-prefetch) 属性。
+
+配置该属性可以在请求资源之前解析域名，降低请求延迟，提升加载性能。
+
+更多信息可参考：[Using dns-prefetch](https://developer.mozilla.org/en-US/docs/Web/Performance/dns-prefetch)
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="performance.dnsPrefetch" />

package/docs/zh/configure/app/performance/preconnect.mdx

@@ -0,0 +1,20 @@
+---
+title: preconnect
+---
+
+# performance.preconnect
+
+- **类型：** `undefined | Array<string | PreconnectOption>`
+
+```ts
+interface PreconnectOption {
+  href: string;
+  crossorigin?: boolean;
+}
+```
+
+- **默认值：** `undefined`
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="performance.preconnect" />

package/docs/zh/configure/app/performance/prefetch.mdx

@@ -0,0 +1,25 @@
+---
+title: prefetch
+---
+
+# performance.prefetch
+
+- **类型：** `undefined | true | PrefetchOption`
+
+```ts
+type IncludeType = 'async-chunks' | 'initial' | 'all-assets' | 'all-chunks';
+
+type Filter = Array<string | RegExp> | ((filename: string) => boolean);
+
+interface PrefetchOption {
+  type?: IncludeType;
+  include?: Filter;
+  exclude?: Filter;
+}
+```
+
+- **默认值：** `undefined`
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="performance.prefetch" />

package/docs/zh/configure/app/performance/preload.mdx

@@ -0,0 +1,27 @@
+---
+title: preload
+---
+
+# performance.preload
+
+- **类型：** `undefined | true | PreloadOption`
+
+```ts
+type IncludeType = 'async-chunks' | 'initial' | 'all-assets' | 'all-chunks';
+
+type Filter = Array<string | RegExp> | ((filename: string) => boolean);
+
+interface PreloadOption {
+  type?: IncludeType;
+  include?: Filter;
+  exclude?: Filter;
+}
+```
+
+- **默认值：** `undefined`
+
+为 Rsbuild 构建生成的静态资源注入 [`<link rel="preload">`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Attributes/rel/preload) 标签。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="performance.preload" />

package/docs/zh/configure/app/performance/print-file-size.mdx

@@ -0,0 +1,44 @@
+---
+title: printFileSize
+---
+
+# performance.printFileSize
+
+- **类型：**
+
+```ts
+type PrintFileSizeOptions =
+  | {
+      /**
+       * 是否输出所有静态资源文件的总体积
+       */
+      total?: boolean;
+      /**
+       * 是否输出每个静态资源文件的体积
+       */
+      detail?: boolean;
+      /**
+       * 是否输出 gzip 压缩后的体积
+       */
+      compressed?: boolean;
+    }
+  | boolean;
+```
+
+- **默认值：** `true`
+
+是否在生产环境构建后输出所有静态资源文件的体积。
+
+```bash
+info    Production file sizes:
+
+  File                                      Size         Gzipped
+  dist/static/js/lib-react.09721b5c.js      152.6 kB     49.0 kB
+  dist/html/main/index.html                 5.8 kB       2.5 kB
+  dist/static/js/main.3568a38e.js           3.5 kB       1.4 kB
+  dist/static/css/main.03221f72.css         1.4 kB       741 B
+```
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="performance.printFileSize" />

package/docs/zh/configure/app/performance/profile.mdx

@@ -0,0 +1,14 @@
+---
+title: profile
+---
+
+# performance.profile
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+是否捕获每个模块的耗时信息，对应 Rspack 的 [profile](https://rspack.rs/zh/config/other-options#profile) 配置。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="performance.profile" />

package/docs/zh/configure/app/performance/remove-console.mdx

@@ -0,0 +1,14 @@
+---
+title: removeConsole
+---
+
+# performance.removeConsole
+
+- **类型：** `boolean | ConsoleType[]`
+- **默认值：** `false`
+
+在生产环境构建时，是否自动移除代码中的 `console.[methodName]`。
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="performance.removeConsole" />