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

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

@@ -0,0 +1,10 @@
+# html.inject
+
+- **Type:** `'head' | 'body' | boolean | Function`
+- **Default:** `'head'`
+
+Set the inject position of the `<script>` tag.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - html.inject](https://v2.rsbuild.dev/config/html/inject).
+:::

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

@@ -0,0 +1,24 @@
+# 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.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - html.meta](https://v2.rsbuild.dev/config/html/meta).
+:::

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

@@ -0,0 +1,10 @@
+# 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`.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - html.mountId](https://v2.rsbuild.dev/config/html/mount-id).
+:::

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

@@ -0,0 +1,10 @@
+# html.outputStructure
+
+- **Type:** `'flat' | 'nested'`
+- **Default:** `'nested'`
+
+Define the directory structure of the HTML output files.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - html.outputStructure](https://v2.rsbuild.dev/config/html/output-structure).
+:::

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

@@ -0,0 +1,10 @@
+# html.scriptLoading
+
+- **Type:** `'defer' | 'blocking' | 'module'`
+- **Default:** `'defer'`
+
+Used to set how `<script>` tags are loaded.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - html.scriptLoading](https://v2.rsbuild.dev/config/html/script-loading).
+:::

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

@@ -0,0 +1,15 @@
+# html.tags
+
+- **Type:**
+
+```ts
+type TagsConfig = HtmlTag | HtmlTagHandler | Array<HtmlTag | HtmlTagHandler>;
+```
+
+- **Default:** `undefined`
+
+Modifies the tags that are injected into the HTML page.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - html.tags](https://v2.rsbuild.dev/config/html/tags).
+:::

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

@@ -0,0 +1,33 @@
+# 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.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - html.templateParameters](https://v2.rsbuild.dev/config/html/template-parameters).
+:::

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

@@ -0,0 +1,10 @@
+# html.template
+
+- **Type:** `string | Function`
+- **Default:**
+
+Specifies the file path for the HTML template, which can be a relative or absolute path.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - html.template](https://v2.rsbuild.dev/config/html/template).
+:::

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

@@ -0,0 +1,18 @@
+# html.title
+
+- **Type:** `string ｜ Function`
+- **Default:** `''`
+
+Set the title tag of the HTML page, for example:
+
+```js
+export default {
+  html: {
+    title: 'example',
+  },
+};
+```
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - html.title](https://v2.rsbuild.dev/config/html/title).
+:::

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

@@ -0,0 +1,11 @@
+# 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.
+
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.assetPrefix](https://v2.rsbuild.dev/config/output/asset-prefix).
+:::

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

@@ -0,0 +1,77 @@
+# 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`](/configure/app/output/asset-prefix.md) 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.md

@@ -0,0 +1,10 @@
+# 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.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.charset](https://v2.rsbuild.dev/config/output/charset).
+:::

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

@@ -0,0 +1,16 @@
+# 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.md

@@ -0,0 +1,79 @@
+# 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.md

@@ -0,0 +1,10 @@
+# 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).
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.copy](https://v2.rsbuild.dev/config/output/copy).
+:::

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

@@ -0,0 +1,48 @@
+# 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.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.cssModules](https://v2.rsbuild.dev/config/output/css-modules).
+:::

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

@@ -0,0 +1,26 @@
+# 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.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.dataUriLimit](https://v2.rsbuild.dev/config/output/data-uri-limit).
+:::

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

@@ -0,0 +1,55 @@
+# output.disableCssModuleExtension
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+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/configure/app/output/disable-inline-runtime-chunk.md

@@ -0,0 +1,41 @@
+# output.disableInlineRuntimeChunk
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+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 Rspack.
+
+runtimeChunk is a piece of runtime code, which is provided by Rspack, that contains the necessary module processing logic, such as module loading, module parsing, etc. See [Runtime Chunk](https://rspack.rs/config/optimization#optimizationruntimechunk) 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/configure/app/output/disable-svgr.md

@@ -0,0 +1,18 @@
+# output.disableSvgr
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether to transform SVGs into React components. If true, will treat all .svg files as assets.
+
+By default, when an SVG resource is referenced in a JS file, Modern.js will call SVGR to convert the SVG into a React component. If you are sure that all SVG resources in your project are not being used as React components, you can turn off this conversion by setting `disableSvgr` to true to improve build performance.
+
+Modern.js runs the built-in SVGR transform through Rsbuild's parallel worker mode when SVGR is enabled.
+
+```js
+export default {
+  output: {
+    disableSvgr: true,
+  },
+};
+```

package/docs/configure/app/output/disable-ts-checker.md

@@ -0,0 +1,49 @@
+# output.disableTsChecker
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether to disable TypeScript type checker during compilation.
+
+By default, Modern.js will run TypeScript checks through the TS-Go native preview toolchain during the build process. You can use `tsconfig.json` or `tools.tsChecker` config to customize the checking behavior.
+
+### Blocking Compilation
+
+- In development build, type errors will not block the compilation process.
+- In production build, type errors will cause the build to fail to ensure the stability of the production code.
+
+### Example
+
+Disable TypeScript type checker:
+
+```js
+export default {
+  output: {
+    disableTsChecker: true,
+  },
+};
+```
+
+Disable type checker in development:
+
+```js
+export default {
+  output: {
+    disableTsChecker: process.env.NODE_ENV === 'development',
+  },
+};
+```
+
+Disable type checker in production:
+
+```js
+export default {
+  output: {
+    disableTsChecker: process.env.NODE_ENV === 'production',
+  },
+};
+```
+
+:::tip
+It is not recommended to disable type checker in production, which will reduce the stability of the production code, please use it with caution.
+:::

package/docs/configure/app/output/dist-path.md

@@ -0,0 +1,43 @@
+# output.distPath
+
+
+- **Type：**
+
+```ts
+type DistPathConfig = {
+  root?: string;
+  html?: string;
+  js?: string;
+  css?: string;
+  svg?: string;
+  font?: string;
+  wasm?: string;
+  image?: string;
+  media?: string;
+  worker?: string;
+  assets?: string;
+};
+```
+
+- **Default：**
+
+```js
+const defaultDistPath = {
+  root: 'dist',
+  css: 'static/css',
+  svg: 'static/svg',
+  font: 'static/font',
+  html: 'html',
+  wasm: 'static/wasm',
+  image: 'static/image',
+  media: 'static/media',
+  js: 'static/js',
+  assets: 'static/assets',
+};
+```
+
+Set the directory of the dist files. Modern.js will output files to the corresponding subdirectory according to the file type.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.distPath](https://v2.rsbuild.dev/config/output/dist-path).
+:::