@modern-js/main-doc 2.69.5 → 3.0.0-alpha.0

package/docs/en/components/ua-polyfill.mdx

@@ -1,19 +1,23 @@
-
 ### Polyfill At Runtime
 
 Modern.js also provides a runtime Polyfill solution based on browser [UA](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/User-Agent) information, which has the following advantages over Babel:
 
-- It will not be inserted into the code, reducing the code .
-- The same browser will share a Polyfill code. Therefore, with more and more projects, the UA-based Polyfill code will be delivered faster and faster.
+- It will not be inserted into the code, and only delivers Polyfill code on-demand based on the device accessing the page, reducing the overall code size.
+- The same browser will share a Polyfill code. Therefore, with more and more projects, the UA-based Polyfill code will be delivered faster and faster, with overall speed exceeding conventional solutions.
 
-exec `pnpm run new` to enable this features:
+Modern.js provides the `@modern-js/plugin-polyfill` plugin to implement this feature. You can enable it by installing the plugin:
 
-```bash
-? Please select the operation you want: Enable features
-? Please select the feature name: Enable UA-based Polyfill Feature
-```
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs
+  command={{
+    npm: 'npm install @modern-js/plugin-polyfill',
+    yarn: 'yarn add @modern-js/plugin-polyfill',
+    pnpm: 'pnpm add @modern-js/plugin-polyfill',
+  }}
+/>
 
-After executing the command, register the Polyfill plugin in `modern.config.ts`:
+Then register the Polyfill plugin in `modern.config.ts`:
 
 ```ts title="modern.config.ts"
 import { polyfillPlugin } from '@modern-js/plugin-polyfill';
@@ -23,18 +27,18 @@ export default defineConfig({
 });
 ```
 
-After configuring `output.polyfill` as `ua` and executing `pnpm run build & & pnpm run serve` to start the server, visiting the page can see that the HTML artifacts contains the following script:
+After configuring `output.polyfill` as `ua` and executing `pnpm run build && pnpm run serve` to start the server, visiting the page can see that the HTML artifacts contains the following script:
 
 ```js
 <script src="/__polyfill__" crossorigin></script>
 ```
 
-Visit the page `http://localhost:8080/__polyfill__` on Chrome 51 to see:
+When accessing the page on Chrome 51, you can see the content returned by `http://localhost:8080/__polyfill__` as follows:
 
 ![ua-polyfill](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/ua-polyfill.png)
 
 :::caution
 This feature only works when using Modern.js built-in Web Server.
 
-If you need to customize the HTML template, please refer to [HTML Template](/guides/basic-features/html.html). Manually modifying the template through html.template / tools.html will cause this feature not work.
+If you need to customize the HTML template, please refer to [HTML Template](/guides/basic-features/html.html). Manually modifying the template through `html.template` or `tools.html` may cause this feature to not work correctly.
 :::

package/docs/en/configure/_meta.json

@@ -32,20 +32,20 @@
   },
   {
     "type": "dir",
-    "name": "app/server",
-    "label": "server",
+    "name": "app/resolve",
+    "label": "resolve",
     "collapsed": true
   },
   {
     "type": "dir",
-    "name": "app/output",
-    "label": "output",
+    "name": "app/server",
+    "label": "server",
     "collapsed": true
   },
   {
     "type": "dir",
-    "name": "app/deploy",
-    "label": "deploy",
+    "name": "app/output",
+    "label": "output",
     "collapsed": true
   },
   "app/plugins",
@@ -73,6 +73,5 @@
     "label": "experiments",
     "collapsed": true
   },
-  "app/builder-plugins",
-  "app/auto-load-plugin"
+  "app/builder-plugins"
 ]

package/docs/en/configure/app/bff/cross-project.mdx

@@ -0,0 +1,24 @@
+---
+title: crossProject
+---
+
+# bff.crossProject
+
+- **Type:** `boolean`
+- **Default:** `false`
+
+import EnableBFFCaution from "@site-docs-en/components/enable-bff-caution";
+
+<EnableBFFCaution />
+
+This configuration is used to enable BFF cross-project invocation functionality. When enabled, the current project can be used as a BFF producer, generating an SDK that can be directly called by other projects.
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    crossProject: true,
+  },
+});
+```
+
+For detailed configuration and usage of BFF cross-project invocation, please refer to the [BFF Cross-Project Invocation Guide](/guides/advanced-features/bff/cross-project.html).

package/docs/en/configure/app/dev/lazy-compilation.mdx

@@ -0,0 +1,45 @@
+---
+title: lazyCompilation
+---
+
+# dev.lazyCompilation
+
+- **Type:**
+
+```ts
+type LazyCompilationOptions =
+  | boolean
+  | {
+      /**
+       * Enable lazy compilation for entries.
+       */
+      entries?: boolean;
+      /**
+       * Enable lazy compilation for dynamic imports.
+       */
+      imports?: boolean;
+      /**
+       * Specify which imported modules should be lazily compiled.
+       */
+      test?: RegExp | ((m: Module) => boolean);
+      /**
+       * The path to a custom runtime code that overrides the default lazy compilation client.
+       */
+      client?: string;
+      /**
+       * Tells the client the server URL that needs to be requested.
+       */
+      serverUrl?: string;
+    };
+```
+
+- **Default:** `false`
+
+Enable lazy compilation (compilation on demand), implemented based on Rspack's [lazy compilation](https://rspack.rs/guide/features/lazy-compilation) feature.
+
+import RsbuildLink from '@site/src/components/RsbuildLink';
+
+:::info
+The usage of this configuration item is exactly the same as that of Rsbuild. For detailed information, please refer to <RsbuildLink configName="dev.lazyCompilation"/>。
+In Rspack build mode,
+:::

package/docs/en/configure/app/dev/server.mdx

@@ -0,0 +1,103 @@
+---
+title: server
+---
+
+# dev.server
+
+- **Type:** `Object`
+- **Default:** `{}`
+
+The config of DevServer can be modified through `dev.server`.
+
+### compress
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Whether to enable gzip compression for served static assets.
+
+If you want to disable the gzip compression, you can set `compress` to `false`:
+
+```ts
+export default {
+  dev: {
+    server: {
+      compress: false,
+    },
+  },
+};
+```
+
+For more details, please refer to the [Rsbuild - server.compress](https://rsbuild.rs/config/server/compress) documentation.
+
+### headers
+
+- **Type:** `Record<string, string>`
+- **Default:** `undefined`
+
+Adds headers to all responses.
+
+```js
+export default {
+  dev: {
+    server: {
+      headers: {
+        'X-Custom-Foo': 'bar',
+      },
+    },
+  },
+};
+```
+
+For more details, please refer to the [Rsbuild - server.headers](https://rsbuild.rs/config/server/headers) documentation.
+
+### historyApiFallback
+
+- **Type:** `boolean | ConnectHistoryApiFallbackOptions`
+- **Default:** `false`
+
+The index.html page will likely have to be served in place of any 404 responses. Enable `dev.server.historyApiFallback` by setting it to `true`:
+
+```js
+export default {
+  dev: {
+    server: {
+      historyApiFallback: true,
+    },
+  },
+};
+```
+
+For more configuration options, please refer to the [Rsbuild - server.historyApiFallback](https://rsbuild.rs/config/server/history-api-fallback) documentation.
+
+### watch
+
+- **Type:** `boolean`
+- **Default:** `true`
+
+Whether to watch files change in directories such as `mock/`, `server/`, `api/`.
+
+For more details, please refer to the [Rsbuild - dev.watchFiles](https://rsbuild.rs/config/dev/watch-files) documentation.
+
+### cors
+
+- **Type:** `boolean | import('cors').CorsOptions`
+
+Configure CORS (Cross-Origin Resource Sharing) for the development server.
+
+The default configuration for `cors` in Modern.js follows Rsbuild's defaults:
+
+```ts
+const defaultAllowedOrigins =
+  /^https?:\/\/(?:(?:[^:]+\.)?localhost|127\.0\.0\.1|\[::1\])(?::\d+)?$/;
+
+const defaultOptions = {
+  // Default allowed:
+  // - localhost
+  // - 127.0.0.1
+  // - [::1]
+  origin: defaultAllowedOrigins
+};
+```
+
+For more configuration options and detailed usage, please refer to the [Rsbuild - server.cors](https://rsbuild.rs/config/server/cors) documentation.

package/docs/en/configure/app/dev/setup-middlewares.mdx

@@ -7,31 +7,13 @@ title: setupMiddlewares
 - **Type:**
 
 ```ts
-type SetupMiddlewaresServer = {
+type RequestHandler = (req: any, res: any, next: () => void) => void;
+
+type ExposeServerApis = {
   sockWrite: (
     type: string,
     data?: string | boolean | Record<string, any>,
   ) => void;
-  environments: {
-    [name: string]: {
-      /**
-       * Get stats info about current environment.
-       */
-      getStats: () => Promise<Stats>;
-      /**
-       * Load and execute stats bundle in server.
-       *
-       * @param entryName - relate to Rsbuild's `source.entry`
-       * @returns the return value of entry module.
-       */
-      loadBundle: <T = unknown>(entryName: string) => Promise<T>;
-
-      /**
-       * Get the compiled HTML template.
-       */
-      getTransformedHtml: (entryName: string) => Promise<string>;
-    };
-  };
 };
 
 type SetupMiddlewares = Array<
@@ -40,7 +22,7 @@ type SetupMiddlewares = Array<
       unshift: (...handlers: RequestHandler[]) => void;
       push: (...handlers: RequestHandler[]) => void;
     },
-    server: SetupMiddlewaresServer,
+    server: ExposeServerApis,
   ) => void
 >;
 ```

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

@@ -13,7 +13,7 @@ type AppIconItem = {
   target?: 'apple-touch-icon' | 'web-app-manifest';
 };
 
-type AppIcon = string | {
+type AppIcon = {
   name?: string;
   icons: AppIconItem[];
   filename?: string;
@@ -27,28 +27,6 @@ Set the web application icons to display when added to the home screen of a mobi
 - Generate the web app manifest file and its `icons` field.
 - Generate the `apple-touch-icon` and `manifest` tags in the HTML file.
 
-### AppIcon string
-
-The `appIcon` configuration of type `string` is a syntactic sugar for the `object` type.
-
-```js
-export default {
-  html: {
-    appIcon: './src/assets/icon.png',
-  },
-};
-```
-
-The above configuration is equivalent to the following configuration:
-
-```js
-export default {
-  html: {
-    appIcon: { icons: [{ src: './src/assets/icon.png', size: 180 }] }
-  },
-};
-```
-
 import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
 
 <RsbuildConfig configName="html.appIcon" />

package/docs/en/configure/app/output/inline-scripts.mdx

@@ -20,7 +20,7 @@ type InlineScripts =
     };
 ```
 
-- **Default:** `false`
+- **Default:** `/builder-runtime([.].+)?\.js$/`
 
 Whether to inline output scripts files (.js files) into HTML with `<script>` tags.
 

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

@@ -9,15 +9,17 @@ title: overrideBrowserslist
 
 ```ts
 const defaultBrowserListMap: Record<RsbuildTarget, string[]> = {
-  web: ['> 0.01%', 'not dead', 'not op_mini all'],
+  web: ['chrome >= 87', 'edge >= 88', 'firefox >= 78', 'safari >= 14'],
   node: ['node >= 14'],
-  'web-worker': ['> 0.01%', 'not dead', 'not op_mini all'],
+  'web-worker': ['chrome >= 87', 'edge >= 88', 'firefox >= 78', 'safari >= 14'],
 };
 ```
 
-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.
 
-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.
+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.
+
+For other configuration methods and configuration priorities, please refer to the [Browserslist configuration](/guides/advanced-features/compatibility.html).
 
 import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
 

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

@@ -19,12 +19,15 @@ type SourceMap =
 
 ```ts
 const defaultSourceMap = {
-  js: isDev ? 'cheap-module-source-map' : false,
-  css: false,
+  js: isDev ? 'cheap-module-source-map' : 'hidden-source-map',
+  css: isDev,
 };
 ```
 
-Used to set whether to generate source map files, and which format of source map to generate.
+When `output.sourceMap` is not configured, the source map generation rules of Modern.js are different from Rsbuild:
+
+- In the development mode, JS and CSS source maps are generated for development debugging.
+- In the production mode, JS source maps are generated for stack trace backtracking, and CSS source maps are not generated to provide the best build performance.
 
 import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
 

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

@@ -11,10 +11,19 @@ Configuration to enable the application’s SSG (Static Site Generation) feature
 
 :::tip Enabling SSG
 This configuration takes effect only when SSG is enabled. Please read the [Static Site Generation](/guides/basic-features/render/ssg) documentation to understand how to enable SSG and its use cases.
+
 :::
 
 :::info Recommended Reading
-The SSG feature is closely related to routing. It is recommended to understand the [routing solution](/guides/basic-features/routes) before using SSG.
+The SSG feature is closely related to routing. It is recommended to understand the [routing solution](/guides/basic-features/routes/routes) before using SSG.
+
+:::
+
+:::info
+- Use `output.ssg` for single-entry apps.
+- For multi-entry apps, prefer `output.ssgByEntries`.
+- If `output.ssg` is `true` and `output.ssgByEntries` is not set, all routes under all entries are treated as SSG routes.
+
 :::
 
 ## Boolean Type
@@ -29,36 +38,6 @@ export default defineConfig({
 });
 ```
 
-`output.ssg` can also be configured per entry, with the rules for effective configurations determined by the entry's routing method.
-
-For example, given the following directory structure, there are conventional routing entry `entryA` and manual routing entry `entryB`:
-
-```bash
-.
-└── src
-    ├── entryA
-    │   └── routes
-    └── entryB
-        └── App.tsx
-```
-
-You can specify different SSG configurations for `entryA` and `entryB`:
-
-```js
-export default defineConfig({
-  output: {
-    ssg: {
-      entryA: true,
-      entryB: false,
-    },
-  },
-});
-```
-
-:::info
-For more information on the default behavior of **conventional routing** and **manual routing** after enabling SSG, please read [Static Site Generation](/guides/basic-features/render/ssg).
-:::
-
 ## Object Type
 
 When the value type is `Object`, the following attributes can be configured.
@@ -70,12 +49,10 @@ type SSGRouteOptions =
   | string
   | {
       url: string;
-      params?: Record<string, any>[];
       headers?: Record<string, any>;
     };
 
 type SSGOptions = {
-  preventDefault?: string[];
   headers?: Record<string, any>;
   routes?: SSGRouteOptions[];
 };
@@ -85,7 +62,7 @@ type SSGOptions = {
 
 In the example configuration below, SSG will render the pages corresponding to the `/`, `/about`, and `/user/:id` routes.
 
-For the `/user/:id` route, `cookies` will be added to the request headers, and the `id` in `params` will be replaced with `modernjs`.
+For the `/user/:id` route, `cookies` will be added to the request headers.
 
 ```ts title="modern.config.ts"
 export default defineConfig({
@@ -95,15 +72,10 @@ export default defineConfig({
         '/',
         '/about',
         {
-          url: '/user/:id',
+          url: '/user/modernjs',
           headers: {
             cookies: 'name=modernjs',
           },
-          params: [
-            {
-              id: 'modernjs',
-            },
-          ],
         },
       ],
     },
@@ -111,6 +83,3 @@ export default defineConfig({
 });
 ```
 
-:::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/ssgByEntries.mdx

@@ -0,0 +1,93 @@
+---
+title: ssgByEntries
+---
+
+# output.ssgByEntries
+
+- **Type:** `Record<string, boolean | object>`
+- **Default Value:** `undefined`
+
+Configure SSG per entry for multi-entry applications.
+
+:::info
+- Use `output.ssg` for single-entry apps.
+- For multi-entry apps, prefer `output.ssgByEntries`.
+- If `output.ssg` is `true` and `output.ssgByEntries` is not set, all routes under all entries are treated as SSG routes.
+
+:::
+
+## Configuration Type
+
+```ts
+type SSGRouteOptions =
+  | string
+  | {
+      url: string;
+      headers?: Record<string, any>;
+    };
+
+type SSGOptions = {
+  headers?: Record<string, any>;
+  routes?: SSGRouteOptions[];
+};
+
+// ssgByEntries type
+type SSGMultiEntryOptions = Record<string, boolean | SSGOptions>;
+```
+
+## Examples
+
+### Enable SSG for some entries
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  output: {
+    ssgByEntries: {
+      home: true,
+      admin: false,
+    },
+  },
+});
+```
+
+### Configure routes per entry
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  output: {
+    ssgByEntries: {
+      home: {
+        routes: ['/', '/about', '/user/modernjs'],
+      },
+      admin: {
+        routes: ['/', '/dashboard'],
+      },
+    },
+  },
+});
+```
+
+### Configure headers per entry or route
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  output: {
+    ssgByEntries: {
+      home: {
+        headers: {
+          'x-tt-env': 'ppe_modernjs',
+        },
+        routes: [
+          '/',
+          {
+            url: '/about',
+            headers: {
+              from: 'modern-website',
+            },
+          },
+        ],
+      },
+    },
+  },
+});
+```

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

@@ -38,10 +38,6 @@ export default {
 };
 ```
 
-::: warning
-Starting from `v2.69.0`, Modern.js using rspack as build tool will enable buildCache by default; previous versions required manual configuration to enable it.
-:::
-
 import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
 
 <RsbuildConfig configName="performance.buildCache" />

package/docs/en/configure/app/resolve/alias-strategy.mdx

@@ -0,0 +1,14 @@
+---
+title: aliasStrategy
+---
+
+# resolve.aliasStrategy
+
+- **Type:** `'prefer-tsconfig' | 'prefer-alias'`
+- **Default:** `'prefer-tsconfig'`
+
+Set the strategy for path alias resolution, to control the priority relationship between the paths option in `tsconfig.json` and the [resolve.alias](https://rsbuild.rs/config/resolve/alias) option of Rsbuild.
+
+import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="resolve.aliasStrategy" />

package/docs/en/configure/app/resolve/alias.mdx

@@ -0,0 +1,13 @@
+---
+title: alias
+---
+
+# resolve.alias
+
+- **Type:** `string[]`
+
+Create aliases for module paths to simplify import paths or redirect module references.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="resolve.alias" />

package/docs/en/configure/app/resolve/condition-names.mdx

@@ -0,0 +1,18 @@
+---
+title: conditionNames
+---
+
+# resolve.conditionNames
+
+- **Type:** `string[]`
+- **Default:** Same as Rspack's `resolve.conditionNames`
+
+Specifies the condition names used to match entry points in the [exports](https://nodejs.org/api/packages.html#packages_exports) of a package.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="resolve.extensions" />
+
+:::warning
+Do not enable this configuration option for SSR applications, as it will cause SSR rendering to fail.
+:::

package/docs/en/configure/app/resolve/dedupe.mdx

@@ -0,0 +1,13 @@
+---
+title: dedupe
+---
+
+# resolve.dedupe
+
+- **Type:** `string[]`
+
+Force Rsbuild to resolve the specified packages from project root, which is useful for deduplicating packages and reducing the bundle size. same as the [resolve.dedupe](https://rsbuild.rs/config/resolve/dedupe) config of Rsbuild.
+
+import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
+
+<RsbuildConfig configName="resolve.dedupe" />