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

package/docs/en/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/en/config/html/templateParameters.md';
+- **Type:** `Record<string, unknown> | Function`
+- **Default:**
 
-<Main />
+```ts
+type DefaultParameters = {
+  mountId: string; // the value of `html.mountId` config
+  entryName: string; // entry name
+  assetPrefix: string; // the value of dev.assetPrefix or output.assetPrefix configs
+  compilation: Compilation; // Compilation object of Rspack
+  rspackConfig: Rspack.Configuration; // Rspack config object
+  // generated by html-rspack-plugin
+  htmlPlugin: {
+    tags: {
+      headTags: HtmlTagObject[];
+      bodyTags: HtmlTagObject[];
+    };
+    files: {
+      publicPath: string;
+      js: Array<string>;
+      css: Array<string>;
+      favicon?: string;
+    };
+  };
+};
+```
+
+Define the parameters in the HTML template, corresponding to the `templateParameters` config of [html-rspack-plugin](https://github.com/rspack-contrib/html-rspack-plugin). You can use the config as an object or a function.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

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

@@ -1,9 +1,15 @@
 ---
 title: template
+configName: html.template
 ---
 
 # html.template
 
-import Main from '@modern-js/builder-doc/docs/en/config/html/template.md';
+- **Type:** `string | Function`
+- **Default:**
 
-<Main />
+Specifies the file path for the HTML template, which can be a relative or absolute path.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/html/title-by-entries.mdx

@@ -4,6 +4,34 @@ title: titleByEntries
 
 # html.titleByEntries
 
-import Main from '@modern-js/builder-doc/docs/en/config/html/titleByEntries.md';
+- **Type:** `Record<string, string>`
+- **Default:** `undefined`
+
+Set different title for different pages.
+
+The usage is same as `title`, and you can use the "entry name" as the key to set each page individually.
+
+`titleByEntries` will overrides the value set in `title`.
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use the function usage of `html.title` instead.
+:::
+
+### Example
+
+```js
+export default {
+  html: {
+    title: 'ByteDance',
+    titleByEntries: {
+      foo: 'TikTok',
+    },
+  },
+};
+```
+
+After recompiling, you can see:
+
+- The title of the page `foo` is `TikTok`.
+- The title of other pages is `ByteDance`.
 
-<Main />

package/docs/en/configure/app/html/title.mdx

@@ -1,9 +1,23 @@
 ---
 title: title
+configName: html.title
 ---
 
 # html.title
 
-import Main from '@modern-js/builder-doc/docs/en/config/html/title.md';
+- **Type:** `string ｜ Function`
+- **Default:** `''`
 
-<Main />
+Set the title tag of the HTML page, for example:
+
+```js
+export default {
+  html: {
+    title: 'example',
+  },
+};
+```
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/output/asset-prefix.mdx

@@ -1,9 +1,19 @@
 ---
 title: assetPrefix
+configName: output.assetPrefix
 ---
 
 # output.assetPrefix
 
-import Main from '@modern-js/builder-doc/docs/en/config/output/assetPrefix.md';
+- **Type:** `string | 'auto'`
+- **Default:** `'/'`
 
-<Main />
+In production mode, use this option to set the URL prefix for static assets, such as setting it to a CDN URL.
+
+import OutputAssetPrefixExtend from '@site-docs-en/components/output-asset-prefix-extend';
+
+<OutputAssetPrefixExtend />
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

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

@@ -4,6 +4,76 @@ title: assetsRetry
 
 # output.assetsRetry
 
-import Main from '@modern-js/builder-doc/docs/en/config/output/assetsRetry.md';
+- **Type:** `Object`
 
-<Main />
+`output.assetsRetry` is used to configure the retry of assets.The type of `AssetsRetryOptions` is as follows:
+
+```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;
+};
+```
+
+- **Default:** `undefined`
+
+Since the ability will inject some extra runtime code into HTML, we have disabled this ability by default. If you need to enable it, you can configure it in the form of an object, for example:
+
+```js
+export default {
+  output: {
+    assetsRetry: {},
+  },
+};
+```
+
+When you enable this ability, the default config of `assetsRetry` is as follows:
+
+```ts
+export const defaultAssetsRetryOptions: AssetsRetryOptions = {
+  type: ['script', 'link', 'img'],
+  domain: [],
+  max: 3,
+  test: '',
+  crossOrigin: false,
+  onRetry: () => {},
+  onSuccess: () => {},
+  onFail: () => {},
+};
+```
+
+### Example
+
+You can also customize your retry logic using the `assetsRetry` options.
+
+For example, setting `assetsRetry.domain` to specify the retry domain when assets fail to load.
+
+```js
+export default {
+  output: {
+    assetsRetry: {
+      domain: ['https://cdn1.com', 'https://cdn2.com', 'https://cdn3.com'],
+    },
+  },
+};
+```
+
+After adding the above configuration, when assets fail to load from the `cdn1.com` domain, the request domain will automatically fallback to `cdn2.com`.
+
+If the assets request for `cdn2.com` also fails, the request will fallback to `cdn3.com`.
+
+`assetsRetry` is implemented based on the Assets Retry plugin of Rsbuild and provides the same configuration options. You can refer to [Rsbuild - Assets Retry Plugin](https://rsbuild.dev/plugins/list/plugin-assets-retry#options) to understand all available configuration options.

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

@@ -1,9 +1,15 @@
 ---
 title: charset
+configName: output.charset
 ---
 
 # output.charset
 
-import Main from '@modern-js/builder-doc/docs/en/config/output/charset.md';
+- **Type:** `'ascii' | 'utf8'`
+- **Default:** `'ascii'`
 
-<Main />
+The `charset` config allows you to specify the [character encoding](https://developer.mozilla.org/en-US/docs/Glossary/Character_encoding) for output files to ensure they are displayed correctly in different environments.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

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

@@ -4,6 +4,17 @@ title: cleanDistPath
 
 # output.cleanDistPath
 
-import Main from '@modern-js/builder-doc/docs/en/config/output/cleanDistPath.md';
+- **Type:** `boolean`
+- **Default:** `true`
 
-<Main />
+Whether to clean all files in the dist path before starting compilation.
+
+By default, Modern.js will automatically clean up the files in the dist directory, you can disable this behavior by setting `cleanDistPath` to `false`.
+
+```js
+export default {
+  output: {
+    cleanDistPath: false,
+  },
+};
+```

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

@@ -4,6 +4,80 @@ title: convertToRem
 
 # output.convertToRem
 
-import Main from '@modern-js/builder-doc/docs/en/config/output/convertToRem.md';
+- **Type:** `boolean | object`
+- **Default:** `false`
 
-<Main />
+By setting `output.convertToRem`, Modern.js can do the following things:
+
+- Convert px to rem in CSS.
+- Insert runtime code into the HTML template to set the fontSize of the root element.
+
+### Boolean Type
+
+If `output.convertToRem` is set to `true`, Rem processing capability will be turned on.
+
+```js
+export default {
+  output: {
+    convertToRem: true,
+  },
+};
+```
+
+At this point, the rem configuration defaults as follows:
+
+```js
+{
+  enableRuntime: true,
+  rootFontSize: 50,
+  screenWidth: 375,
+  rootFontSize: 50,
+  maxRootFontSize: 64,
+  widthQueryKey: '',
+  excludeEntries: [],
+  supportLandscape: false,
+  useRootFontSizeBeyondMax: false,
+  pxtorem: {
+    rootValue: 50,
+    unitPrecision: 5,
+    propList: ['*'],
+  }
+}
+```
+
+### Object Type
+
+When the value of `output.convertToRem` is `object` type, Modern.js will perform Rem processing based on the current configuration.
+
+options:
+
+| Name                     | Type       | Default                                                                                                              | Description                                                                                                                                                                        |
+| ------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| enableRuntime            | `boolean`  | `true`                                                                                                               | Whether to generate runtime code to calculate and set the font size of the root element                                                                                            |
+| inlineRuntime            | `boolean`  | `true`                                                                                                               | Whether to inline the runtime code to HTML. If set to `false`, the runtime code will be extracted into a separate `convert-rem.[version].js` file and output to the dist directory |
+| rootFontSize             | `number`   | `50`                                                                                                                 | The root element font size                                                                                                                                                         |
+| maxRootFontSize          | `number`   | `64`                                                                                                                 | The root element max font size                                                                                                                                                     |
+| widthQueryKey            | `string`   | `'' `                                                                                                                | Get clientWidth from the url query based on widthQueryKey                                                                                                                          |
+| screenWidth              | `number`   | `375`                                                                                                                | The screen width for UI design drawings (Usually, `fontSize = (clientWidth * rootFontSize) / screenWidth`)                                                                         |
+| excludeEntries           | `string[]` | `[]`                                                                                                                 | To exclude some page entries from injecting runtime code, it is usually used with `pxtorem.exclude`                                                                                |
+| supportLandscape         | `boolean`  | `false`                                                                                                              | Use height to calculate rem in landscape                                                                                                                                           |
+| useRootFontSizeBeyondMax | `boolean`  | `false`                                                                                                              | Whether to use rootFontSize when large than maxRootFontSize                                                                                                                        |
+| pxtorem                  | `object`   | <ul><li>rootValue (Default is the same as rootFontSize) </li><li>unitPrecision: 5 </li><li>propList: ['*']</li></ul> | [postcss-pxtorem](https://github.com/cuth/postcss-pxtorem#options) options                                                                                                         |
+
+### Example
+
+```js
+export default {
+  output: {
+    convertToRem: {
+      rootFontSize: 30,
+      excludeEntries: ['404', 'page2'],
+      pxtorem: {
+        propList: ['font-size'],
+      },
+    },
+  },
+};
+```
+
+For detailed usage, please refer to [rsbuild-plugin-rem](https://github.com/rspack-contrib/rsbuild-plugin-rem).

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

@@ -4,6 +4,9 @@ title: copy
 
 # output.copy
 
-import Main from '@modern-js/builder-doc/docs/en/config/output/copy.md';
+- **Type:**`Rspack.CopyRspackPluginOptions | Rspack.CopyRspackPluginOptions['patterns']`
+- **Default:** `undefined`
 
-<Main />
+Copies the specified file or directory to the dist directory, implemented based on [rspack.CopyRspackPlugin](https://rspack.dev/zh/plugins/rspack/copy-rspack-plugin).
+
+For more detailed configuration, please refer to: [rspack.CopyRspackPlugin](https://rspack.dev/zh/plugins/rspack/copy-rspack-plugin).

package/docs/en/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/en/config/output/cssModuleLocalIdentName.md';
+- **Type:** `string`
+- **Default:**
 
-<Main />
+```ts
+// isProd indicates that the production build
+const localIdentName = isProd
+  ? '[local]-[hash:base64:6]'
+  : '[path][name]__[local]-[hash:base64:6]';
+```
+
+Sets the format of the className generated by CSS Modules after compilation.
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use the `cssModules.localIdentName` instead.
+:::

package/docs/en/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/en/config/output/cssModules.md';
+- **Type:**
 
-<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;
+};
+```
+
+- **Default:**
+
+```ts
+const defaultCssModules = {
+  auto: true,
+  namedExport: false,
+  exportGlobals: false,
+  exportLocalsConvention: 'camelCase',
+};
+```
+
+For custom CSS Modules configuration.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/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/en/config/output/dataUriLimit.md';
+- **Type：**
 
-<Main />
+```ts
+type DataUriLimitConfig =
+  | number
+  | {
+      svg?: number;
+      font?: number;
+      image?: number;
+      media?: number;
+    };
+```
+
+- **Default：**
+
+```js
+const defaultDatUriLimit = 10000;
+```
+
+Set the size threshold to inline static assets such as images and fonts.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

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

@@ -4,6 +4,13 @@ title: disableCssExtract
 
 # output.disableCssExtract
 
-import Main from '@modern-js/builder-doc/docs/en/config/output/disableCssExtract.md';
+- **Type:** `boolean`
+- **Default:** `false`
 
-<Main />
+Whether to disable CSS extract and inline CSS files into JS files.
+
+By default, Modern.js will extract CSS into a separate `.css` file and output it to the dist directory. When this option is set to `true`, CSS files will be inlined into JS files and inserted on the page at runtime via `<style>` tags.
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use the `output.injectStyles` instead.
+:::

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

@@ -4,6 +4,56 @@ title: disableCssModuleExtension
 
 # output.disableCssModuleExtension
 
-import Main from '@modern-js/builder-doc/docs/en/config/output/disableCssModuleExtension.md';
+- **Type:** `boolean`
+- **Default:** `false`
 
-<Main />
+Whether to treat all `.css` files in the source directory as CSS Modules.
+
+By default, only the `*.module.css` files are treated as CSS Modules. After enabling this config, all `*.css` style files in the source directory will be regarded as CSS Modules.
+
+`.sass`, `.scss` and `.less` files are also affected by `disableCssModuleExtension`.
+
+:::tip
+We do not recommend enabling this config, because after enabling `disableCssModuleExtension`, CSS Modules files and ordinary CSS files cannot be clearly distinguished, which is not conducive to long-term maintenance.
+:::
+
+### Example
+
+```js
+export default {
+  output: {
+    disableCssModuleExtension: true,
+  },
+};
+```
+
+### Detailed
+
+The following is a detailed explanation of the CSS Modules rules:
+
+#### disableCssModuleExtension is false (default)
+
+The following files are treated as CSS Modules:
+
+- all `*.module.css` files
+
+The following files are treated as normal CSS:
+
+- all `*.css` files (excluding `.module`)
+- all `*.global.css` files
+
+#### disableCssModuleExtension is true
+
+The following files are treated as CSS Modules:
+
+- `*.css` and `*.module.css` files in the source directory
+- `*.module.css` files under node_modules
+
+The following files are treated as normal CSS:
+
+- all `*.global.css` files
+- `*.css` files under node_modules (without `.module`)
+
+:::tip
+For CSS Modules files inside node_modules, please always use the `*.module.css` suffix.
+:::

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

@@ -4,6 +4,13 @@ title: disableFilenameHash
 
 # output.disableFilenameHash
 
-import Main from '@modern-js/builder-doc/docs/en/config/output/disableFilenameHash.md';
+- **Type:** `boolean`
+- **Default:** `false`
 
-<Main />
+Remove the hash from the name of static files after production build.
+
+After the production build, there will be a hash in the middle of the filename by default. You can disable this behavior through the `output.disableFilenameHash` config.
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use the boolean usage of `output.filenameHash` instead.
+:::

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

@@ -4,6 +4,42 @@ title: disableInlineRuntimeChunk
 
 # output.disableInlineRuntimeChunk
 
-import Main from '@modern-js/builder-doc/docs/en/config/output/disableInlineRuntimeChunk.md';
+- **Type:** `boolean`
+- **Default:** `false`
 
-<Main />
+Used to control whether to inline the bundler's runtime code into HTML.
+
+:::tip What is runtimeChunk
+Modern.js will generate a `builder-runtime.js` file in the dist directory, which is the runtime code of webpack or Rspack.
+
+runtimeChunk is a piece of runtime code, which is provided by webpack or Rspack, that contains the necessary module processing logic, such as module loading, module parsing, etc. See [Runtime](https://webpack.js.org/concepts/manifest/#runtime) for details.
+
+:::
+
+In the production environment, Modern.js will inline the runtimeChunk file into the HTML file by default instead of writing it to the dist directory. This is done to reduce the number of file requests.
+
+### Disable Inlining
+
+If you don't want the runtimeChunk file to be inlined into the HTML file, you can set `disableInlineRuntimeChunk` to `true` and a separate `builder-runtime.js` file will be generated.
+
+```js
+export default {
+  output: {
+    disableInlineRuntimeChunk: true,
+  },
+};
+```
+
+### Merge Into Page Chunk
+
+If you don't want to generate a separate runtimeChunk file, but want the runtimeChunk code to be bundled into the page chunk, you can set the config like this:
+
+```js
+export default {
+  tools: {
+    bundlerChain(chain) {
+      chain.optimization.runtimeChunk(false);
+    },
+  },
+};
+```

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

@@ -4,6 +4,11 @@ title: disableMinimize
 
 # output.disableMinimize
 
-import Main from '@modern-js/builder-doc/docs/en/config/output/disableMinimize.md';
+- **Type:** `boolean`
+- **Default:** `false`
 
-<Main />
+Whether to disable code minification on production builds.
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use the boolean usage of `output.minify` instead.
+:::

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

@@ -4,6 +4,28 @@ title: disableSourceMap
 
 # output.disableSourceMap
 
-import Main from '@modern-js/builder-doc/docs/en/config/output/disableSourceMap.md';
+- **Type:**
 
-<Main />
+```ts
+type DisableSourceMap =
+  | boolean
+  | {
+      js?: boolean;
+      css?: boolean;
+    };
+```
+
+- **Default:**
+
+```ts
+const defaultDisableSourceMap = {
+  js: false,
+  css: process.env.NODE_ENV === 'production',
+};
+```
+
+Whether to disable Source Map generation.
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use the boolean usage of `output.sourceMap` instead.
+:::