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

package/docs/en/configure/app/html/mount-id.mdx

@@ -1,9 +1,15 @@
 ---
 title: mountId
+configName: html.mountId
 ---
 
 # html.mountId
 
-import Main from '@modern-js/builder-doc/docs/en/config/html/mountId.md';
+- **Type:** `string`
+- **Default:** `'root'`
 
-<Main />
+By default, the `root` element is included in the HTML template for component mounting, and the element id can be modified through `mountId`.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/html/script-loading.mdx

@@ -1,9 +1,15 @@
 ---
 title: scriptLoading
+configName: html.scriptLoading
 ---
 
 # html.scriptLoading
 
-import Main from '@modern-js/builder-doc/docs/en/config/html/scriptLoading.md';
+- **Type:** `'defer' | 'blocking' | 'module'`
+- **Default:** `'defer'`
 
-<Main />
+Used to set how `<script>` tags are loaded.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

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

@@ -4,6 +4,41 @@ title: tagsByEntries
 
 # html.tagsByEntries
 
-import Main from '@modern-js/builder-doc/docs/en/config/html/tagsByEntries.md';
+- **Type:** `Record<string, ArrayOrNot<HtmlInjectTag | HtmlInjectTagHandler>>`
+- **Default:** `undefined`
+
+Used for multiple entry applications, injecting different tags for each entry.
+
+The usage is the same as `tags`, and you can use the "entry name" as the key to set each page individually.
+
+`tagsByEntries` will override the value set in `tags`.
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use the function usage of `html.tags` instead.
+:::
+
+### Example
+
+```js
+export default {
+  html: {
+    tags: [{ tag: 'script', attrs: { src: 'a.js' } }],
+    tagsByEntries: {
+      foo: [{ tag: 'script', attrs: { src: 'b.js' } }],
+    },
+  },
+};
+```
+
+Compile the application and you can see a tag injected on the `foo` page:
+
+```html
+<script src="b.js"></script>
+```
+
+And for any other pages:
+
+```html
+<script src="a.js"></script>
+```
 
-<Main />

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

@@ -1,9 +1,20 @@
 ---
 title: tags
+configName: html.tags
 ---
 
 # html.tags
 
-import Main from '@modern-js/builder-doc/docs/en/config/html/tags.md';
+- **Type:**
 
-<Main />
+```ts
+type TagsConfig = HtmlTag | HtmlTagHandler | Array<HtmlTag | HtmlTagHandler>;
+```
+
+- **Default:** `undefined`
+
+Modifies the tags that are injected into the HTML page.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

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

@@ -4,6 +4,30 @@ title: templateByEntries
 
 # html.templateByEntries
 
-import Main from '@modern-js/builder-doc/docs/en/config/html/templateByEntries.md';
+- **Type:** `Object`
+- **Default:** `undefined`
+
+Set different template file for different pages.
+
+The usage is same as `template`, and you can use the "entry name" as the key to set each page individually.
+
+`templateByEntries` will overrides the value set in `template`.
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use the function usage of `html.template` instead.
+:::
+
+### Example
+
+```js
+export default {
+  html: {
+    template: './static/index.html',
+    templateByEntries: {
+      foo: './src/pages/foo/index.html',
+      bar: './src/pages/bar/index.html',
+    },
+  },
+};
+```
 
-<Main />

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

@@ -4,6 +4,32 @@ title: templateParametersByEntries
 
 # html.templateParametersByEntries
 
-import Main from '@modern-js/builder-doc/docs/en/config/html/templateParametersByEntries.md';
+- **Type:** `Object`
+- **Default:** `undefined`
 
-<Main />
+Set different template parameters for different pages.
+
+The usage is same as `templateParameters`, and you can use the "entry name" as the key to set each page individually.
+
+`templateParametersByEntries` will overrides the value set in `templateParameters`.
+
+:::warning
+**Deprecated**: This configuration is deprecated, please use the function usage of `html.templateParameters` instead.
+:::
+
+### Example
+
+```js
+export default {
+  html: {
+    templateParametersByEntries: {
+      foo: {
+        type: 'a',
+      },
+      bar: {
+        type: 'b',
+      },
+    },
+  },
+};
+```

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.
+:::