@bleedingdev/modern-js-app-tools 3.5.0-ultramodern.98 → 3.5.0-ultramodern.99

package/docs/configure/app/dev/watch-files.mdx

@@ -0,0 +1,31 @@
+---
+title: watchFiles
+---
+
+# dev.watchFiles
+
+- **Type:**
+
+```ts
+type WatchFiles =
+  | {
+      paths: string | string[];
+      type?: 'reload-page';
+      // watch options for chokidar
+      options?: WatchOptions;
+    }
+  | {
+      paths: string | string[];
+      type?: 'reload-server';
+    };
+
+type WatchFilesConfig = WatchFiles | WatchFiles[];
+```
+
+- **Default:** `undefined`
+
+Watch specified files and directories for changes. When a file change is detected, it can trigger a page reload or restart the dev server.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="dev.watchFiles" />

package/docs/configure/app/dev/write-to-disk.mdx

@@ -0,0 +1,14 @@
+---
+title: writeToDisk
+---
+
+# dev.writeToDisk
+
+- **Type:** `boolean | ((filename: string) => boolean)`
+- **Default:** `(file) => !file.includes('.hot-update.')`
+
+Controls whether the build output from development mode is written to disk.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="dev.writeToDisk" />

package/docs/configure/app/experiments/source-build.mdx

@@ -0,0 +1,33 @@
+---
+title: sourceBuild
+---
+
+- **Type:** `boolean | PluginSourceBuildOptions`
+- **Default:** `false`
+
+Used to enable the ability for source code building. When this configuration option is enabled, Modern.js will read the source code files corresponding to the `source` field in the sub-project's package.json and compile them.
+
+```ts
+export default {
+  experiments: {
+    sourceBuild: true,
+  },
+};
+```
+
+More detail can see ["Source Code Build Mode"](https://modernjs.dev/en/guides/advanced-features/source-build.html)。
+
+### Options
+
+`experiments.sourceBuild` is implemented based on [@rsbuild/plugin-source-build](https://github.com/rstackjs/rsbuild-plugin-source-build?tab=readme-ov-file#options). You can pass plugin options like this:
+
+```ts
+export default {
+  experiments: {
+    sourceBuild: {
+      sourceField: 'my-source',
+      resolvePriority: 'output',
+    },
+  },
+};
+```

package/docs/configure/app/html/app-icon.mdx

@@ -0,0 +1,32 @@
+---
+title: appIcon
+---
+
+# html.appIcon
+
+- **Type:**
+
+```ts
+type AppIconItem = {
+  src: string;
+  size: number;
+  target?: 'apple-touch-icon' | 'web-app-manifest';
+};
+
+type AppIcon = {
+  name?: string;
+  icons: AppIconItem[];
+  filename?: string;
+};
+```
+
+- **Default:** `undefined`
+
+Set the web application icons to display when added to the home screen of a mobile device:
+
+- Generate the web app manifest file and its `icons` field.
+- Generate the `apple-touch-icon` and `manifest` tags in the HTML file.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="html.appIcon" />

package/docs/configure/app/html/crossorigin.mdx

@@ -0,0 +1,14 @@
+---
+title: crossorigin
+---
+
+# html.crossorigin
+
+- **Type:** `boolean | 'anonymous' | 'use-credentials'`
+- **Default:** `false`
+
+Set the [crossorigin](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) attribute of the `<script>` and `<style>` tags.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="html.crossorigin" />

package/docs/configure/app/html/favicon.mdx

@@ -0,0 +1,20 @@
+---
+title: favicon
+---
+
+# html.favicon
+
+- **Type:** `string ｜ Function`
+- **Default:** `undefined`
+
+Set the favicon icon path for all pages, can be set as:
+
+- a URL.
+- an absolute path to the file.
+- a relative path relative to the project root directory.
+
+After config this option, the favicon will be automatically copied to the dist directory during the compilation, and the corresponding `link` tag will be added to the HTML.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="html.favicon" />

package/docs/configure/app/html/inject.mdx

@@ -0,0 +1,14 @@
+---
+title: inject
+---
+
+# html.inject
+
+- **Type:** `'head' | 'body' | boolean | Function`
+- **Default:** `'head'`
+
+Set the inject position of the `<script>` tag.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="html.inject" />

package/docs/configure/app/html/meta.mdx

@@ -0,0 +1,28 @@
+---
+title: meta
+---
+
+# html.meta
+
+- **Type:** `Object | Function`
+- **Default:**
+
+```js
+const defaultMeta = {
+  charset: { charset: 'utf-8' },
+  viewport:
+    'width=device-width, initial-scale=1.0, shrink-to-fit=no, viewport-fit=cover, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no',
+  'http-equiv': { 'http-equiv': 'x-ua-compatible', content: 'ie=edge' },
+  renderer: 'webkit',
+  layoutmode: 'standard',
+  imagemode: 'force',
+  'wap-font-scale': 'no',
+  'format-detection': 'telephone=no',
+};
+```
+
+Configure the `<meta>` tag of the HTML.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="html.meta" />

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

@@ -0,0 +1,14 @@
+---
+title: mountId
+---
+
+# html.mountId
+
+- **Type:** `string`
+- **Default:** `'root'`
+
+By default, the `root` element is included in the HTML template for component mounting, and the element id can be modified through `mountId`.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="html.mountId" />

package/docs/configure/app/html/output-structure.mdx

@@ -0,0 +1,14 @@
+---
+title: outputStructure
+---
+
+# html.outputStructure
+
+- **Type:** `'flat' | 'nested'`
+- **Default:** `'nested'`
+
+Define the directory structure of the HTML output files.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="html.outputStructure" />

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

@@ -0,0 +1,14 @@
+---
+title: scriptLoading
+---
+
+# html.scriptLoading
+
+- **Type:** `'defer' | 'blocking' | 'module'`
+- **Default:** `'defer'`
+
+Used to set how `<script>` tags are loaded.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="html.scriptLoading" />

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

@@ -0,0 +1,19 @@
+---
+title: tags
+---
+
+# html.tags
+
+- **Type:**
+
+```ts
+type TagsConfig = HtmlTag | HtmlTagHandler | Array<HtmlTag | HtmlTagHandler>;
+```
+
+- **Default:** `undefined`
+
+Modifies the tags that are injected into the HTML page.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="html.tags" />

package/docs/configure/app/html/template-parameters.mdx

@@ -0,0 +1,37 @@
+---
+title: templateParameters
+---
+
+# html.templateParameters
+
+- **Type:** `Record<string, unknown> | Function`
+- **Default:**
+
+```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/rstackjs/html-rspack-plugin). You can use the config as an object or a function.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="html.templateParameters" />

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

@@ -0,0 +1,14 @@
+---
+title: template
+---
+
+# html.template
+
+- **Type:** `string | Function`
+- **Default:**
+
+Specifies the file path for the HTML template, which can be a relative or absolute path.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="html.template" />

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

@@ -0,0 +1,22 @@
+---
+title: title
+---
+
+# html.title
+
+- **Type:** `string ｜ Function`
+- **Default:** `''`
+
+Set the title tag of the HTML page, for example:
+
+```js
+export default {
+  html: {
+    title: 'example',
+  },
+};
+```
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="html.title" />

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

@@ -0,0 +1,18 @@
+---
+title: assetPrefix
+---
+
+# output.assetPrefix
+
+- **Type:** `string | 'auto'`
+- **Default:** `'/'`
+
+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 RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="output.assetPrefix" />

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

@@ -0,0 +1,81 @@
+---
+title: assetsRetry
+---
+
+# output.assetsRetry
+
+- **Type:** `Object`
+
+`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 this feature injects some runtime code into your HTML and [Rspack Runtime](https://rspack.rs/api/runtime-api/module-variables), it is disabled by default. To enable it, provide an object for the option, for example:
+
+```js
+export default {
+  output: {
+    assetsRetry: {},
+  },
+};
+```
+
+When you enable this feature, the default configuration for `assetsRetry` is:
+
+```ts
+export const defaultAssetsRetryOptions: AssetsRetryOptions = {
+  type: ['script', 'link', 'img'],
+  domain: [],
+  max: 3,
+  test: '',
+  crossOrigin: false,
+  inlineScript: 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.
+
+As an example, you can specify a list of fallback domains via `assetsRetry.domain`. The first domain in the list should match the domain used in your [`assetsPrefix`](./asset-prefix.mdx) configuration:
+
+```js
+export default {
+  output: {
+    assetsRetry: {
+      domain: ['cdn1.com', 'cdn2.com', 'cdn3.com'],
+    },
+    assetsPrefix: 'https://cdn1.com', // or '//cdn1.com'
+  },
+};
+```
+
+With the configuration above, if an asset fails to load from `cdn1.com`, requests will automatically fall back to `cdn2.com`. If `cdn2.com` also fails, the request will continue 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://github.com/rstackjs/rsbuild-plugin-assets-retry) to understand all available configuration options.

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

@@ -0,0 +1,14 @@
+---
+title: charset
+---
+
+# output.charset
+
+- **Type:** `'ascii' | 'utf8'`
+- **Default:** `'ascii'`
+
+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 RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="output.charset" />

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

@@ -0,0 +1,20 @@
+---
+title: cleanDistPath
+---
+
+# output.cleanDistPath
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+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/configure/app/output/convert-to-rem.mdx

@@ -0,0 +1,83 @@
+---
+title: convertToRem
+---
+
+# output.convertToRem
+
+- **Type:** `boolean | object`
+- **Default:** `false`
+
+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/rstackjs/rsbuild-plugin-rem).

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

@@ -0,0 +1,14 @@
+---
+title: copy
+---
+
+# output.copy
+
+- **Type:**`Rspack.CopyRspackPluginOptions | Rspack.CopyRspackPluginOptions['patterns']`
+- **Default:** `undefined`
+
+Copies the specified file or directory to the dist directory, implemented based on [rspack.CopyRspackPlugin](https://rspack.rs/zh/plugins/rspack/copy-rspack-plugin).
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="output.copy" />

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

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

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

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