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

package/docs/en/configure/app/output/legal-comments.mdx

@@ -1,9 +1,23 @@
 ---
 title: legalComments
+configName: output.legalComments
 ---
 
 # output.legalComments
 
-import Main from '@modern-js/builder-doc/docs/en/config/output/legalComments.md';
+- **Type:** `'linked' | 'inline' | 'none'`
+- **Default:** `'linked'`
 
-<Main />
+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.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

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

@@ -0,0 +1,27 @@
+---
+title: minify
+configName: output.minify
+---
+
+# 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.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/output/override-browserslist.mdx

@@ -1,9 +1,25 @@
 ---
 title: overrideBrowserslist
+configName: output.overrideBrowserslist
 ---
 
 # output.overrideBrowserslist
 
-import Main from '@modern-js/builder-doc/docs/en/config/output/overrideBrowserslist.md';
+- **Type:** `string[] | undefined`
+- **Default:**
 
-<Main />
+```ts
+const defaultBrowserListMap: Record<RsbuildTarget, string[]> = {
+  web: ['> 0.01%', 'not dead', 'not op_mini all'],
+  node: ['node >= 14'],
+  'web-worker': ['> 0.01%', 'not dead', 'not op_mini all'],
+};
+```
+
+Modern.js will give priority to using the configuration in the `.browserslistrc` file in the project root directory.
+
+Specifies the range of target browsers that the project is compatible with. This value will be used by [SWC](https://github.com/swc-project/swc) and [autoprefixer](https://github.com/postcss/autoprefixer) to identify the JavaScript syntax that need to be transformed and the CSS browser prefixes that need to be added.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

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

@@ -1,9 +1,19 @@
 ---
 title: polyfill
+configName: output.polyfill
 ---
 
 # output.polyfill
 
-import Main from '@modern-js/builder-doc/docs/en/config/output/polyfill.md';
+- **Type:** `'entry' | 'usage' | 'ua' | 'off'`
+- **Default:** `'entry'`
 
-<Main />
+Via `output.polyfill` you can configure how the polyfill is injected.
+
+import OutputPolyfillExtend from '@site-docs-en/components/output-polyfill-extend';
+
+<OutputPolyfillExtend />
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

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

@@ -0,0 +1,30 @@
+---
+title: sourceMap
+configName: output.sourceMap
+---
+
+# output.sourceMap
+
+- **Type:**
+
+```ts
+type SourceMap = {
+  js?: Rspack.Configuration['devtool'];
+  css?: boolean;
+};
+```
+
+- **Default:**
+
+```ts
+const defaultSourceMap = {
+  js: isDev ? 'cheap-module-source-map' : false,
+  css: false,
+};
+```
+
+Used to set whether to generate source map files, and which format of source map to generate.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

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

@@ -4,7 +4,7 @@ title: ssg
 
 # output.ssg
 
-- **Type:** `boolean` | `object`
+- **Type:** `boolean | object`
 - **Default Value:** `undefined`
 
 Configuration to enable the application’s SSG (Static Site Generation) feature.
@@ -65,13 +65,14 @@ When the value type is `Object`, the following attributes can be configured.
 
 ### Configuration Type
 
-
 ```ts
-type SSGRouteOptions = string | {
-  url: string;
-  params?: Record<string, any>[];
-  headers?: Record<string, any>;
-};
+type SSGRouteOptions =
+  | string
+  | {
+      url: string;
+      params?: Record<string, any>[];
+      headers?: Record<string, any>;
+    };
 
 type SSGOptions = {
   preventDefault?: string[];
@@ -91,23 +92,25 @@ export default defineConfig({
   output: {
     ssg: {
       routes: [
-        '/', 
-        '/about',         
+        '/',
+        '/about',
         {
           url: '/user/:id',
           headers: {
-            cookies: "name=modernjs"
+            cookies: 'name=modernjs',
           },
-          params: [{
-            id: 'modernjs',
-          }],
-        }
+          params: [
+            {
+              id: 'modernjs',
+            },
+          ],
+        },
       ],
-    }
-  }
+    },
+  },
 });
 ```
 
 :::note
 The configuration method for multiple entries is the same as for a single entry, so it will not be explained further here.
-:::
+:::

package/docs/en/configure/app/output/svg-default-export.mdx

@@ -4,6 +4,31 @@ title: svgDefaultExport
 
 # output.svgDefaultExport
 
-import Main from '@modern-js/builder-doc/docs/en/config/output/svgDefaultExport.md';
+- **Type:** `'url' | 'component'`
+- **Default:** `'url'`
 
-<Main />
+`output.svgDefaultExport` is used to configure the default export type of SVG files.
+
+When `output.svgDefaultExport` is set to `url` , the default export of SVG files is the URL of the file. For example:
+
+```js
+import logo from './logo.svg';
+
+console.log(logo); // => asset url
+```
+
+When `output.svgDefaultExport` is set to `component` , the default export of SVG files is the React component of the file. For example:
+
+```js
+import Logo from './logo.svg';
+
+console.log(Logo); // => React Component
+```
+
+At this time, you can also specify the `?url` query to import the URL, for example:
+
+```js
+import logo from './logo.svg?url';
+
+console.log(logo); // => asset url
+```

package/docs/en/configure/app/performance/build-cache.mdx

@@ -4,6 +4,82 @@ title: buildCache
 
 # performance.buildCache
 
-import Main from '@modern-js/builder-doc/docs/en/config/performance/buildCache.md';
+- **Type:**
 
-<Main />
+```ts
+type BuildCacheConfig =
+  | {
+      /**
+       * Base directory for the filesystem cache.
+       */
+      cacheDirectory?: string;
+      /**
+       * Set different cache names based on cacheDigest content.
+       */
+      cacheDigest?: Array<string | undefined>;
+    }
+  | boolean;
+```
+
+- **Default:**
+
+```js
+const defaultBuildCacheConfig = {
+  cacheDirectory: './node_modules/.cache/webpack',
+};
+```
+
+- **Bundler:** `only support webpack`
+
+Controls the caching behavior during the build process.
+
+Modern.js will enable build cache by default to improve the compile speed, the generated cache files are write to the `./node_modules/.cache/webpack` directory by default.
+
+You can configure the cache path with `buildCache`, e.g.
+
+```js
+export default {
+  performance: {
+    buildCache: {
+      cacheDirectory: './node_modules/.custom_cache/webpack',
+    },
+  },
+};
+```
+
+You can also disable the build cache by setting it to `false`:
+
+```js
+export default {
+  performance: {
+    buildCache: false,
+  },
+};
+```
+
+### cacheDigest
+
+`cacheDigest` is used to add some environment variables that will affect the build results. Modern.js will set the cache name based on the `cacheDigest` content and the current build mode to ensure that different cacheDigests can hit different caches.
+
+#### Example
+
+The current project needs to set different extensions according to different `APP_ID`. By default, since the code & configuration & dependencies of the current project have not changed, the previous cache will be hit.
+
+By adding `APP_ID` to `cacheDigest`, different cache results will be searched when APP_ID changes, thereby avoiding hitting cache results that do not meet expectations.
+
+```js
+export default {
+  tools: {
+    bundlerChain: (chain: any) => {
+      if (process.env.APP_ID === 'xxx') {
+        chain.resolve.extensions.prepend('.ttp.ts');
+      }
+    },
+  },
+  performance: {
+    buildCache: {
+      cacheDigest: [process.env.APP_ID],
+    },
+  },
+};
+```

package/docs/en/configure/app/performance/bundle-analyze.mdx

@@ -1,9 +1,25 @@
 ---
 title: bundleAnalyze
+configName: performance.bundleAnalyze
 ---
 
 # performance.bundleAnalyze
 
-import Main from '@modern-js/builder-doc/docs/en/config/performance/bundleAnalyze.md';
+- **Type:** `Object | undefined`
 
-<Main />
+Used to enable the [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) plugin to analyze the size of the output.
+
+By default, Modern.js does not enable `webpack-bundle-analyzer`. When this feature is enabled, the default configuration is as follows:
+
+```js
+const defaultConfig = {
+  analyzerMode: 'static',
+  openAnalyzer: false,
+  // Distinguish by target names, such as `web`, `node`, etc.
+  reportFilename: `report-${target}.html`,
+};
+```
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/performance/chunk-split.mdx

@@ -1,9 +1,45 @@
 ---
 title: chunkSplit
+configName: performance.chunkSplit
 ---
 
 # performance.chunkSplit
 
-import Main from '@modern-js/builder-doc/docs/en/config/performance/chunkSplit.md';
+- **Type:** `Object`
+- **Default:** `{ strategy: 'split-by-experience' }`
 
-<Main />
+`performance.chunkSplit` is used to configure the chunk splitting strategy. The type of `ChunkSplit` is as follows:
+
+```ts
+type ForceSplitting = RegExp[] | Record<string, RegExp>;
+
+interface BaseChunkSplit {
+  strategy?:
+    | 'split-by-module'
+    | 'split-by-experience'
+    | 'all-in-one'
+    | 'single-vendor';
+  override?: SplitChunks;
+  forceSplitting?: ForceSplitting;
+}
+
+interface SplitBySize {
+  strategy?: 'split-by-size';
+  minSize?: number;
+  maxSize?: number;
+  override?: SplitChunks;
+  forceSplitting?: ForceSplitting;
+}
+
+interface SplitCustom {
+  strategy?: 'custom';
+  splitChunks?: SplitChunks;
+  forceSplitting?: ForceSplitting;
+}
+
+export type ChunkSplit = BaseChunkSplit | SplitBySize | SplitCustom;
+```
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/performance/dns-prefetch.mdx

@@ -1,9 +1,20 @@
 ---
 title: dnsPrefetch
+configName: performance.dnsPrefetch
 ---
 
 # performance.dnsPrefetch
 
-import Main from '@modern-js/builder-doc/docs/en/config/performance/dnsPrefetch.md';
+- **Type:** `undefined | string[]`
 
-<Main />
+- **Default:** `undefined`
+
+Specifies that the user agent should preemptively perform DNS resolution for the target resource's origin, refer to [dns-prefetch](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/dns-prefetch).
+
+After this property is set, the domain name can be resolved before the resource is requested, reducing request latency and improving loading performance.
+
+See [Using dns-prefetch](https://developer.mozilla.org/en-US/docs/Web/Performance/dns-prefetch) for more details.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/performance/preconnect.mdx

@@ -1,9 +1,21 @@
 ---
 title: preconnect
+configName: performance.preconnect
 ---
 
 # performance.preconnect
 
-import Main from '@modern-js/builder-doc/docs/en/config/performance/preconnect.md';
+- **Type:** `undefined | Array<string | PreconnectOption>`
 
-<Main />
+```ts
+interface PreconnectOption {
+  href: string;
+  crossorigin?: boolean;
+}
+```
+
+- **Default:** `undefined`
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/performance/prefetch.mdx

@@ -1,9 +1,26 @@
 ---
 title: prefetch
+configName: performance.prefetch
 ---
 
 # performance.prefetch
 
-import Main from '@modern-js/builder-doc/docs/en/config/performance/prefetch.md';
+- **Type:** `undefined | true | PrefetchOption`
 
-<Main />
+```ts
+type IncludeType = 'async-chunks' | 'initial' | 'all-assets' | 'all-chunks';
+
+type Filter = Array<string | RegExp> | ((filename: string) => boolean);
+
+interface PrefetchOption {
+  type?: IncludeType;
+  include?: Filter;
+  exclude?: Filter;
+}
+```
+
+- **Default:** `undefined`
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/performance/preload.mdx

@@ -1,9 +1,28 @@
 ---
 title: preload
+configName: performance.preload
 ---
 
 # performance.preload
 
-import Main from '@modern-js/builder-doc/docs/en/config/performance/preload.md';
+- **Type：** `undefined | true | PreloadOption`
 
-<Main />
+```ts
+type IncludeType = 'async-chunks' | 'initial' | 'all-assets' | 'all-chunks';
+
+type Filter = Array<string | RegExp> | ((filename: string) => boolean);
+
+interface PreloadOption {
+  type?: IncludeType;
+  include?: Filter;
+  exclude?: Filter;
+}
+```
+
+- **Default：** `undefined`
+
+Inject the [`<link rel="preload">`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Attributes/rel/preload) tags for the static assets generated by Rsbuild.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/performance/print-file-size.mdx

@@ -1,9 +1,45 @@
 ---
 title: printFileSize
+configName: performance.printFileSize
 ---
 
 # performance.printFileSize
 
-import Main from '@modern-js/builder-doc/docs/en/config/performance/printFileSize.md';
+- **Type:**
 
-<Main />
+```ts
+type PrintFileSizeOptions =
+  | {
+      /**
+       * whether to print total size
+       */
+      total?: boolean;
+      /**
+       * whether to print size of each file
+       */
+      detail?: boolean;
+      /**
+       * whether to print gzip-compressed size
+       */
+      compressed?: boolean;
+    }
+  | boolean;
+```
+
+- **Default:** `true`
+
+Whether to print the file sizes after production build.
+
+```bash
+info    Production file sizes:
+
+  File                                      Size         Gzipped
+  dist/static/js/lib-react.09721b5c.js      152.6 kB     49.0 kB
+  dist/html/main/index.html                 5.8 kB       2.5 kB
+  dist/static/js/main.3568a38e.js           3.5 kB       1.4 kB
+  dist/static/css/main.03221f72.css         1.4 kB       741 B
+```
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/performance/profile.mdx

@@ -1,9 +1,15 @@
 ---
 title: profile
+configName: performance.profile
 ---
 
 # performance.profile
 
-import Main from '@modern-js/builder-doc/docs/en/config/performance/profile.md';
+- **Type:** `boolean`
+- **Default:** `false`
 
-<Main />
+Whether capture timing information for each module, same as the [profile](https://webpack.js.org/configuration/other-options/#profile) config of Rspack.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/performance/remove-console.mdx

@@ -1,9 +1,15 @@
 ---
 title: removeConsole
+configName: performance.removeConsole
 ---
 
 # performance.removeConsole
 
-import Main from '@modern-js/builder-doc/docs/en/config/performance/removeConsole.md';
+- **Type:** `boolean | ConsoleType[]`
+- **Default:** `false`
 
-<Main />
+Whether to remove `console.[methodName]` in production build.
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/performance/remove-moment-locale.mdx

@@ -1,9 +1,15 @@
 ---
 title: removeMomentLocale
+configName: performance.removeMomentLocale
 ---
 
 # performance.removeMomentLocale
 
-import Main from '@modern-js/builder-doc/docs/en/config/performance/removeMomentLocale.md';
+- **Type:** `boolean`
+- **Default:** `false`
 
-<Main />
+Whether to remove the locales of [moment.js](https://momentjs.com/).
+
+import RsbuildConig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConig />

package/docs/en/configure/app/performance/transform-lodash.mdx

@@ -4,6 +4,46 @@ title: transformLodash
 
 # performance.transformLodash
 
-import Main from '@modern-js/builder-doc/docs/en/config/performance/transformLodash.md';
+- **Type:** `boolean`
+- **Default:** `true`
+- **Bundler:** `only support webpack`
 
-<Main />
+Specifies whether to modularize the import of [lodash](https://www.npmjs.com/package/lodash) and remove unused lodash modules to reduce the code size of lodash.
+
+This optimization is implemented using [babel-plugin-lodash](https://www.npmjs.com/package/babel-plugin-lodash) and [swc-plugin-lodash](https://github.com/web-infra-dev/swc-plugins/tree/main/crates/plugin_lodash) under the hood.
+
+### Example
+
+This option is enabled by default, and Modern.js will automatically redirects the code references of `lodash` to sub-paths.
+
+For example:
+
+```ts title="input.js"
+import _ from 'lodash';
+import { add } from 'lodash/fp';
+
+const addOne = add(1);
+_.map([1, 2, 3], addOne);
+```
+
+The transformed code will be:
+
+```ts title="output.js"
+import _add from 'lodash/fp/add';
+import _map from 'lodash/map';
+
+const addOne = _add(1);
+_map([1, 2, 3], addOne);
+```
+
+### Disabling the Transformation
+
+In some cases, the import transformation of `lodash` may generate unexpected code. In such cases, you can manually disable this optimization:
+
+```js
+export default {
+  performance: {
+    transformLodash: false,
+  },
+};
+```