@modern-js/main-doc 2.69.7 → 3.0.0-alpha.1

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

@@ -0,0 +1,211 @@
+---
+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.
+
+### proxy
+
+- **Type:** `Record<string, string> | Record<string, ProxyDetail>`
+- **Default:** `undefined`
+
+Proxy requests to the specified service.
+
+```js
+export default {
+  dev: {
+    server: {
+      proxy: {
+        '/api': 'http://localhost:3000',
+      },
+    },
+  },
+};
+```
+
+At this point, the /api/users request will be proxied to http://localhost:3000/api/users.
+
+If you don't want to pass /api, you can rewrite the request path through `pathRewrite`:
+
+```js
+export default {
+  dev: {
+    server: {
+      proxy: {
+        '/api': {
+          target: 'http://localhost:3000',
+          pathRewrite: { '^/api': '' },
+        },
+      },
+    },
+  },
+};
+```
+
+DevServer Proxy is implemented based on [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware/tree/2.x). You can use all configuration items of http-proxy-middleware, see the documentation for details.
+
+The full type definition of DevServer Proxy is:
+
+```ts
+import type { Options as HttpProxyOptions } from 'http-proxy-middleware';
+
+type Filter = string | string[] | ((pathname: string, req: Request) => boolean);
+
+type ProxyDetail = HttpProxyOptions & {
+  bypass?: (
+    req: IncomingMessage,
+    res: ServerResponse,
+    proxyOptions: ProxyOptions,
+  ) => string | undefined | null | false;
+  context?: Filter;
+};
+
+type ProxyOptions =
+  | Record<string, string>
+  | Record<string, ProxyDetail>
+  | ProxyDetail[]
+  | ProxyDetail;
+```
+
+In addition to the http-proxy-middleware options, two configuration items are also supported: bypass and context:
+
+- bypass: Bypass the proxy based on the return value of the function.
+  - Returning `null` or `undefined` will continue to process the request with proxy.
+  - Returning `false` will return a 404 error.
+  - Returning a specific service path will use this path to replace the original request path.
+- context: If you want to proxy multiple specific paths to the same target, you can use the context configuration item.
+
+```js
+// Custom bypass method
+export default {
+  dev: {
+    server: {
+      proxy: {
+        '/api': {
+          target: 'http://localhost:3000',
+          bypass: function (req, res, proxyOptions) {
+            if (req.headers.accept.indexOf('html') !== -1) {
+              console.log('Skipping proxy for browser request.');
+              return '/index.html';
+            }
+          },
+        },
+      },
+    },
+  },
+};
+```
+
+```js
+// Proxy multiple paths to the same target
+export default {
+  dev: {
+    server: {
+      proxy: [
+        {
+          context: ['/auth', '/api'],
+          target: 'http://localhost:3000',
+        },
+      ],
+    },
+  },
+};
+```

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/experiments/source-build.mdx

@@ -4,7 +4,6 @@ title: sourceBuild
 
 - **Type:** `boolean | PluginSourceBuildOptions`
 - **Default:** `false`
-- **Version:** `MAJOR_VERSION.46.0`
 
 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.
 

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/assets-retry.mdx

@@ -31,7 +31,7 @@ export type AssetsRetryOptions = {
 
 - **Default:** `undefined`
 
-- Since this feature injects some runtime code into your HTML and [webpack/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:
+- 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 {

package/docs/en/configure/app/output/disable-inline-runtime-chunk.mdx

@@ -10,9 +10,9 @@ title: disableInlineRuntimeChunk
 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 webpack or Rspack.
+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 webpack or Rspack, that contains the necessary module processing logic, such as module loading, module parsing, etc. See [Runtime](https://webpack.js.org/concepts/manifest/#runtime) for details.
+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.
 
 :::
 

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

@@ -2,16 +2,14 @@
 title: filename
 ---
 
+# 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.
 
-In common, you don't need to modify the html filename. If you want modify `main.html` to `index.html`, using [source.mainEntryName](/configure/app/source/main-entry-name).
-
 :::
 
-# output.filename
-
 - **Type:**
 
 ```ts

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/output/temp-dir.mdx

@@ -7,7 +7,7 @@ title: tempDir
 - **Type:** `string`
 - **Default:** `''`
 
-When developing or building a project, Modern.js generates real Webpack entries and HTML templates, placing them in a temporary directory.
+When developing or building a project, Modern.js generates real Rspack entries and HTML templates, placing them in a temporary directory.
 
 If you want to start a project with multiple configurations at the same time, you can use this configuration to generate files in different temporary directories to avoid interference with each other.
 
@@ -19,6 +19,6 @@ Example:
 export default {
   output: {
     tempDir: path.join('node_modules', '.temp-dir'),
-  }
-}
+  },
+};
 ```

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

@@ -19,7 +19,7 @@ type BuildCacheConfig =
       cacheDigest?: Array<string | undefined>;
       /**
        * An arrays of additional code dependencies for the build.
-       * Rspack / webpack will use a hash of each of these items and all dependencies to invalidate the filesystem cache.
+       * Rspack will use a hash of each of these items and all dependencies to invalidate the filesystem cache.
        */
       buildDependencies?: string[];
     }
@@ -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/performance/profile.mdx

@@ -7,7 +7,7 @@ title: profile
 - **Type:** `boolean`
 - **Default:** `false`
 
-Whether capture timing information for each module, same as the [profile](https://webpack.js.org/configuration/other-options/#profile) config of Rspack.
+Whether capture timing information for each module, same as the [profile](https://rspack.rs/config/other-options#profile) config of Rspack.
 
 import RsbuildConfig from '@site-docs-en/components/rsbuild-config-tooltip';
 

package/docs/en/configure/app/plugins.mdx

@@ -10,11 +10,9 @@ Used to configure custom Modern.js framework CLI plugins. For information on how
 This option is **specifically for configuring framework CLI plugins**. If you need to configure other types of plugins, use the appropriate configuration method:
 
 - Use [builderPlugins](/configure/app/builder-plugins) for Rsbuild plugins.
-- Use [tools.bundlerChain](/configure/app/tools/bundler-chain) for Rspack or webpack plugins.
-- Use [tools.babel](/configure/app/tools/babel) for Babel plugins.
+- Use [tools.bundlerChain](/configure/app/tools/bundler-chain) for Rspack plugins.
 - Use the [plugins field in runtime config](/configure/app/runtime/plugins) for framework Runtime plugins.
 
-
 ## Examples
 
 Below are examples of using CLI plugins:

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" />