@modern-js/app-tools 3.7.0 → 3.8.0

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,16 @@
+# 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.
+
+```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 the TypeScript type checker in a separate process during the build process. Its checking logic is consistent with TypeScript's native `tsc` command. 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).
+:::

package/docs/configure/app/output/enable-asset-manifest.md

@@ -0,0 +1,36 @@
+# output.enableAssetManifest
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether to generate a manifest file that contains information of all assets.
+
+### Example
+
+Enable asset manifest:
+
+```js
+export default {
+  output: {
+    enableAssetManifest: true,
+  },
+};
+```
+
+After compiler, there will be a `dist/manifest.json` file:
+
+```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"]
+}
+```
+
+If the current project has multiple types of build artifacts, such as including SSR build artifacts, multiple manifest.json files will be generated.
+
+- web artifact: `asset-manifest.json`
+- node artifact: `asset-manifest-node.json`

package/docs/configure/app/output/enable-css-module-tsdeclaration.md

@@ -0,0 +1,28 @@
+# output.enableCssModuleTSDeclaration
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether to generate a TypeScript declaration file for CSS modules.
+
+### Example
+
+Enable CSS module TypeScript declaration:
+
+```js
+export default {
+  output: {
+    enableCssModuleTSDeclaration: true,
+  },
+};
+```
+
+After building, there will be a `.d.ts` file for each CSS module file. For example
+
+```ts
+interface CssExports {
+  title: string;
+}
+export const cssExports: CssExports;
+export default cssExports;
+```

package/docs/configure/app/output/enable-inline-route-manifests.md

@@ -0,0 +1,16 @@
+# output.disableInlineRouteManifests
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+When using convention-based routing, the framework injects routing information into the client for optimization purposes. By default, routing information is injected into the html, but when this is configured to `true`, routing information is injected into a separate JS file.
+
+Example:
+
+```ts
+export default {
+  output: {
+    disableInlineRouteManifests: true,
+  },
+};
+```

package/docs/configure/app/output/externals.md

@@ -0,0 +1,20 @@
+# output.externals
+
+- **Type:**
+
+```ts
+type Externals =
+  | string
+  | object
+  | function
+  | RegExp
+  | Array<string | object | function | RegExp>;
+```
+
+- **Default:** `undefined`
+
+At build time, prevent some `import` dependencies from being packed into bundles in your code, and instead fetch them externally at runtime.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.externals](https://v2.rsbuild.dev/config/output/externals).
+:::

package/docs/configure/app/output/filename-hash.md

@@ -0,0 +1,10 @@
+# output.filenameHash
+
+- **Type:** `boolean | string`
+- **Default:** `true`
+
+Whether to add a hash value to the filename after the production build.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.filenameHash](https://v2.rsbuild.dev/config/output/filename-hash).
+:::

package/docs/configure/app/output/filename.md

@@ -0,0 +1,55 @@
+# output.filename
+
+:::warning
+
+In Modern.js `dev` command or use Modern.js server deployment, don't modify the html output filename. This will cause the page to be 404.
+
+:::
+
+- **Type:**
+
+```ts
+type FilenameConfig = {
+  js?:
+    | string
+    | ((pathData: Rspack.PathData, assetInfo: Rspack.JsAssetInfo) => string);
+  css?: string;
+  svg?: string;
+  font?: string;
+  image?: string;
+  media?: string;
+  assets?: string;
+};
+```
+
+- **Default:**
+
+```js
+// Development mode
+const devDefaultFilename = {
+  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]',
+  assets: '[name].[contenthash:8][ext]',
+};
+
+// Production mode
+const prodDefaultFilename = {
+  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]',
+  assets: '[name].[contenthash:8][ext]',
+};
+```
+
+Sets the filename of dist files.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.filename](https://v2.rsbuild.dev/config/output/filename).
+:::

package/docs/configure/app/output/inject-styles.md

@@ -0,0 +1,10 @@
+# output.injectStyles
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+Whether to inject styles into DOM.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.injectStyles](https://v2.rsbuild.dev/config/output/inject-styles).
+:::

package/docs/configure/app/output/inline-scripts.md

@@ -0,0 +1,29 @@
+# output.inlineScripts
+
+- **Type:**
+
+```ts
+type InlineScriptsTest =
+  | RegExp
+  | ((params: { size: number; name: string }) => boolean);
+
+type InlineScripts =
+  | boolean
+  | InlineScriptsTest
+  | {
+      enable?: boolean | 'auto';
+      test: InlineScriptsTest;
+    };
+```
+
+- **Default:** `/builder-runtime([.].+)?\.js$/`
+
+Whether to inline output scripts files (.js files) into HTML with `<script>` tags.
+
+:::tip
+When using convention-based routing, you need to set [output.splitRouteChunks](/configure/app/output/split-route-chunks.md) to false if this option is turned on.
+:::
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.inlineScripts](https://v2.rsbuild.dev/config/output/inline-scripts).
+:::

package/docs/configure/app/output/inline-styles.md

@@ -0,0 +1,29 @@
+# output.inlineStyles
+
+- **Type:**
+
+```ts
+type InlineStylesTest =
+  | RegExp
+  | ((params: { size: number; name: string }) => boolean);
+
+type InlineStyles =
+  | boolean
+  | InlineStylesTest
+  | {
+      enable?: boolean | 'auto';
+      test: InlineStylesTest;
+    };
+```
+
+- **Default:** `false`
+
+Whether to inline output style files (.css files) into HTML with `<style>` tags.
+
+:::tip
+When using convention-based routing, you need to set [output.splitRouteChunks](/configure/app/output/split-route-chunks.md) to false if this option is turned on.
+:::
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.inlineStyles](https://v2.rsbuild.dev/config/output/inline-styles).
+:::

package/docs/configure/app/output/legal-comments.md

@@ -0,0 +1,18 @@
+# output.legalComments
+
+- **Type:** `'linked' | 'inline' | 'none'`
+- **Default:** `'linked'`
+
+Configure how to handle the legal comment.
+
+A "legal comment" is considered to be any statement-level comment in JS or rule-level comment in CSS that contains `@license` or `@preserve` or that starts with `//!` or `/*!`. These comments are preserved in output files by default since that follows the intent of the original authors of the code.
+
+This behavior can be configured by using one of the following options:
+
+- `linked`: Extract all legal comments to a .LEGAL.txt file and link to them with a comment.
+- `inline`: Preserve all legal comments in original position.
+- `none`: Remove all legal comments.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.legalComments](https://v2.rsbuild.dev/config/output/legal-comments).
+:::

package/docs/configure/app/output/minify.md

@@ -0,0 +1,22 @@
+# output.minify
+
+- **Type:**
+
+```ts
+type Minify =
+  | boolean
+  | {
+      js?: boolean;
+      jsOptions?: SwcJsMinimizerRspackPluginOptions;
+      css?: boolean;
+      cssOptions?: LightningCssMinimizerRspackPluginOptions;
+    };
+```
+
+- **Default:** `true`
+
+Configure whether to enable code minification in production mode, or to configure minimizer options.
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to [Rsbuild - output.minify](https://v2.rsbuild.dev/config/output/minify).
+:::