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

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

@@ -4,6 +4,37 @@ title: enableAssetManifest
 
 # output.enableAssetManifest
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/enableAssetManifest.md';
+- **类型：** `boolean`
+- **默认值：** `false`
 
-<Main />
+是否生成 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

@@ -4,6 +4,29 @@ title: enableCssModuleTSDeclaration
 
 # output.enableCssModuleTSDeclaration
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/enableCssModuleTSDeclaration.md';
+- **类型：** `boolean`
+- **默认值：** `false`
 
-<Main />
+是否生成 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-scripts.mdx

@@ -4,6 +4,19 @@ title: enableInlineScripts
 
 # output.enableInlineScripts
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/enableInlineScripts.md';
+- **类型：**
 
-<Main />
+```ts
+type EnableInlineScripts =
+  | boolean
+  | RegExp
+  | ((params: { size: number; name: string }) => boolean);
+```
+
+- **默认值：** `false`
+
+用来控制生产环境中是否用 `<script>` 标签将产物中的 script 文件（.js 文件）inline 到 HTML 中。
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 `output.inlineScripts` 的布尔用法代替。
+:::

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

@@ -4,6 +4,19 @@ title: enableInlineStyles
 
 # output.enableInlineStyles
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/enableInlineStyles.md';
+- **类型：**
 
-<Main />
+```ts
+type EnableInlineStyles =
+  | boolean
+  | RegExp
+  | ((params: { size: number; name: string }) => boolean);
+```
+
+- **默认值：** `false`
+
+用来控制生产环境中是否用 `<style>` 标签将产物中的 style 文件（.css 文件）inline 到 HTML 中。
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 `output.inlineStyles` 的布尔用法代替。
+:::

package/docs/zh/configure/app/output/enable-latest-decorators.mdx

@@ -4,6 +4,11 @@ title: enableLatestDecorators
 
 # output.enableLatestDecorators
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/enableLatestDecorators.md';
+- **类型：** `boolean`
+- **默认值：** `false`
 
-<Main />
+是否要使用 [新版 decorator 提案](https://github.com/tc39/proposal-decorators/tree/7fa580b40f2c19c561511ea2c978e307ae689a1b) 进行编译。
+
+:::warning
+**Deprecated**：该配置已废弃，请使用 `source.decorators` 配置项代替。
+:::

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

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

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

@@ -1,5 +1,6 @@
 ---
 title: filenameHash
+configName: output.filenameHash
 ---
 
 # output.filenameHash
@@ -7,32 +8,8 @@ title: filenameHash
 - **类型：** `boolean | string`
 - **默认值：** `true`
 
-在生产环境构建后，是否在产物的文件名中添加 hash 值。
+在生产模式构建后，是否在产物的文件名中添加 hash 值。
 
-### 示例
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
 
-默认情况下，构建后的产物名称会包含 hash 值：
-
-```bash
-dist/static/css/index.7879e19d.css
-dist/static/js/index.18a568e5.js
-```
-
-你可以将 `output.filenameHash` 设置为 false 来禁用这个行为：
-
-```js
-export default {
-  output: {
-    filenameHash: false,
-  },
-};
-```
-
-重新构建，产物的名称变为：
-
-```bash
-dist/static/css/index.css
-dist/static/js/index.js
-```
-
-详细用法可参考 [Rsbuild - output.filenameHash](https://rsbuild.dev/zh/config/output/filename-hash)。
+<RsbuildConig />

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

@@ -1,9 +1,54 @@
 ---
 title: filename
+configName: output.filename
 ---
 
 # output.filename
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/filename.md';
+- **类型：**
 
-<Main />
+```ts
+type FilenameConfig = {
+  html?: string;
+  js?:
+    | string
+    | ((pathData: Rspack.PathData, assetInfo: Rspack.JsAssetInfo) => string);
+  css?: string;
+  svg?: string;
+  font?: string;
+  image?: string;
+  media?: 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]',
+};
+
+// 生产模式构建
+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]',
+};
+```
+
+设置构建产物的名称。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

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

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

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

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

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

@@ -0,0 +1,34 @@
+---
+title: inlineStyles
+configName: output.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](https://modernjs.dev/configure/app/output/splitRouteChunks.html) 设置为 false。
+:::
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

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

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

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

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

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

@@ -1,9 +1,27 @@
 ---
 title: overrideBrowserslist
+configName: output.overrideBrowserslist
 ---
 
 # output.overrideBrowserslist
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/overrideBrowserslist.md';
+- **类型：** `string[] | undefined`
+- **默认值：**
 
-<Main />
+```ts
+const defaultBrowserListMap: Record<RsbuildTarget, string[]> = {
+  web: ['> 0.01%', 'not dead', 'not op_mini all'],
+  node: ['node >= 14'],
+  'web-worker': ['> 0.01%', 'not dead', 'not op_mini all'],
+};
+```
+
+指定项目兼容的目标浏览器范围。
+
+该值会被 [SWC](https://github.com/swc-project/swc) 和 [autoprefixer](https://github.com/postcss/autoprefixer) 用来确定需要转换的 JavaScript 语法特性和需要添加的 CSS 浏览器前缀。
+
+Modern.js 会优先使用项目根目录的 `.browserslistrc` 文件中的配置。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

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

@@ -1,9 +1,19 @@
 ---
 title: polyfill
+configName: output.polyfill
 ---
 
 # output.polyfill
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/polyfill.md';
+- **类型：** `'entry' | 'usage' | 'ua' | 'off'`
+- **默认值：** `'entry'`
 
-<Main />
+通过 `output.polyfill` 你可以配置 Polyfill 的注入方式。
+
+import OutputPolyfillExtend from '@site-docs/components/output-polyfill-extend';
+
+<OutputPolyfillExtend />
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

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

@@ -0,0 +1,30 @@
+---
+title: sourceMap
+configName: output.sourceMap
+---
+
+# output.sourceMap
+
+- **类型：**
+
+```ts
+type SourceMap = {
+  js?: Rspack.Configuration['devtool'];
+  css?: boolean;
+};
+```
+
+- **默认值：**
+
+```ts
+const defaultSourceMap = {
+  js: isDev ? 'cheap-module-source-map' : false,
+  css: false,
+};
+```
+
+用于设置是否生成 source map 文件，以及生成哪一种格式的 source map。
+
+import RsbuildConig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

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

@@ -4,7 +4,7 @@ title: ssg
 
 # output.ssg
 
-- **类型：** `boolean` | `object`
+- **类型：** `boolean | object`
 - **默认值：** `undefined`
 
 开启应用 SSG 功能的配置
@@ -66,11 +66,13 @@ export default defineConfig({
 ### 配置类型
 
 ```ts
-type SSGRouteOptions = string | {
-  url: string;
-  params?: Record<string, any>[];
-  headers?: Record<string, any>;
-};
+type SSGRouteOptions =
+  | string
+  | {
+      url: string;
+      params?: Record<string, any>[];
+      headers?: Record<string, any>;
+    };
 
 type SSGOptions = {
   preventDefault?: string[];
@@ -90,20 +92,22 @@ export default defineConfig({
   output: {
     ssg: {
       routes: [
-        '/', 
-        '/about',         
+        '/',
+        '/about',
         {
           url: '/user/:id',
           headers: {
-            cookies: "name=modernjs"
+            cookies: 'name=modernjs',
           },
-          params: [{
-            id: 'modernjs',
-          }],
-        }
+          params: [
+            {
+              id: 'modernjs',
+            },
+          ],
+        },
       ],
-    }
-  }
+    },
+  },
 });
 ```
 

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

@@ -4,6 +4,31 @@ title: svgDefaultExport
 
 # output.svgDefaultExport
 
-import Main from '@modern-js/builder-doc/docs/zh/config/output/svgDefaultExport.md';
+- **类型：** `'url' | 'component'`
+- **默认值：** `'url'`
 
-<Main />
+`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/performance/build-cache.mdx

@@ -4,6 +4,81 @@ title: buildCache
 
 # performance.buildCache
 
-import Main from '@modern-js/builder-doc/docs/zh/config/performance/buildCache.md';
+- **类型：**
 
-<Main />
+```ts
+type BuildCacheConfig =
+  | {
+      /**
+       * webpack 文件缓存系统的缓存目录
+       */
+      cacheDirectory?: string;
+      /**
+       * 根据 cacheDigest 内容设置不同的缓存名称
+       */
+      cacheDigest?: Array<string | undefined>;
+    }
+  | boolean;
+```
+
+- **默认值：**
+
+```js
+const defaultBuildCacheConfig = {
+  cacheDirectory: './node_modules/.cache/webpack',
+};
+```
+
+- **打包工具：** `仅支持 webpack`
+
+控制 Modern.js 在构建过程中的缓存行为。
+
+Modern.js 默认会开启构建缓存来提升二次构建的速度，并默认把生成的缓存文件写到 `./node_modules/.cache/webpack` 目录下。
+
+你可以通过 `buildCache` 配置缓存路径，比如：
+
+```js
+export default {
+  performance: {
+    buildCache: {
+      cacheDirectory: './node_modules/.custom_cache/webpack',
+    },
+  },
+};
+```
+
+如果不希望缓存，你也可以将 `buildCache` 置为 `false` 将其禁用掉：
+
+```js
+export default {
+  performance: {
+    buildCache: false,
+  },
+};
+```
+
+### cacheDigest
+
+`cacheDigest` 用来添加一些会对构建结果产生影响的环境变量。Modern.js 将根据 `cacheDigest` 内容和当前构建模式来设置缓存名称，来确保不同的 `cacheDigest` 可以命中不同的缓存。
+
+#### 示例
+
+当前项目需要根据不同的 `APP_ID` 来设置不同的 extensions。默认情况下，由于当前项目的代码 & 配置 & 依赖未发生变化，会命中之前的缓存。
+通过将 `APP_ID` 添加到 `cacheDigest` 中，在 `APP_ID` 变化时会去查找不同的缓存结果，从而避免命中不符合预期的缓存结果。
+
+```js
+export default {
+  tools: {
+    bundlerChain: chain => {
+      if (process.env.APP_ID === 'xxx') {
+        chain.resolve.extensions.prepend('.ttp.ts');
+      }
+    },
+  },
+  performance: {
+    buildCache: {
+      cacheDigest: [process.env.APP_ID],
+    },
+  },
+};
+```