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

package/docs/zh/components/prerequisites.mdx

@@ -9,7 +9,7 @@ import NodeVersion from '@site-docs/components/nodeVersion.mdx';
 推荐使用 [pnpm](https://pnpm.io/installation) 来管理依赖：
 
 ```bash
-npm install -g pnpm@9
+npm install -g pnpm@10
 ```
 
 :::note

package/docs/zh/components/self-route-example.mdx

@@ -1,13 +1,13 @@
 ```tsx title="src/App.tsx"
 import { BrowserRouter, Route, Routes } from '@modern-js/runtime/router';
 import { StaticRouter } from '@modern-js/runtime/router/server';
-import React from 'react';
-import { useRuntimeContext } from '@modern-js/runtime';
+import { use } from 'react';
+import { RuntimeContext } from '@modern-js/runtime';
 
 const Router = typeof window === 'undefined' ? StaticRouter : BrowserRouter;
 
 export default () => {
-  const { context } = useRuntimeContext();
+  const context = use(RuntimeContext);
   const pathname = context?.request?.pathname;
   return (
     <Router location={pathname}>

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

@@ -5,14 +5,19 @@ Modern.js 中还提供了基于浏览器 [UA](https://developer.mozilla.org/zh-C
 - 不会插入到代码中，只根据访问页面的设备，按需下发 Polyfill 代码 ，减少整体代码体积。
 - 相同浏览器会公用一份 Polyfill 代码。因此，随着项目越来越多，基于 UA 的 Polyfill 代码下发速度会越来越快，综合速度超过常规方案。
 
-可以通过微生成器开启该功能：
+Modern.js 提供了 `@modern-js/plugin-polyfill` 插件来实现该功能，可以通过安装该插件来开启该功能：
 
-```bash
-? 请选择你想要的操作 启用可选功能
-? 请选择功能名称 启用「基于 UA 的 Polyfill」功能
-```
+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',
+  }}
+/>
 
-执行命令后，在 `modern.config.ts` 中注册 Polyfill 插件:
+然后在 `modern.config.ts` 中注册 Polyfill 插件:
 
 ```ts title="modern.config.ts"
 import { polyfillPlugin } from '@modern-js/plugin-polyfill';

package/docs/zh/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/zh/configure/app/bff/cross-project.mdx

@@ -0,0 +1,24 @@
+---
+title: crossProject
+---
+
+# bff.crossProject
+
+- **类型：** `boolean`
+- **默认值：** `false`
+
+import EnableBFFCaution from "@site-docs/components/enable-bff-caution";
+
+<EnableBFFCaution />
+
+该配置用于启用 BFF 跨项目调用功能。启用后，可以将当前项目作为 BFF 生产端，生成可被其他项目直接调用的 SDK。
+
+```ts title="modern.config.ts"
+export default defineConfig({
+  bff: {
+    crossProject: true,
+  },
+});
+```
+
+有关 BFF 跨项目调用的详细配置和使用方法，请参考 [BFF 跨项目调用指南](/guides/advanced-features/bff/cross-project.html)。

package/docs/zh/configure/app/builder-plugins.mdx

@@ -18,8 +18,7 @@ Rsbuild 是 Modern.js 底层的构建工具，请阅读 [构建能力](/guides/c
 该选项**用于配置 Rsbuild 构建插件**，如果你需要配置其他类型的插件，请选择对应的配置方式：
 
 - 配置 Modern.js 框架插件，请使用 [plugins](/configure/app/plugins) 配置项。
-- 配置 Rspack 或 webpack 插件，请使用 [tools.bundlerChain](/configure/app/tools/bundler-chain) 配置项。
-- 配置 Babel 插件，请使用 [tools.babel](/configure/app/tools/babel) 配置项。
+- 配置 Rspack 插件，请使用 [tools.bundlerChain](/configure/app/tools/bundler-chain) 配置项。
 
 ## 何时使用
 

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

@@ -0,0 +1,44 @@
+---
+title: lazyCompilation
+---
+
+# dev.lazyCompilation
+
+- **类型：**
+
+```ts
+type LazyCompilationOptions =
+  | boolean
+  | {
+      /**
+       * 为 entries 启用 lazy compilation
+       */
+      entries?: boolean;
+      /**
+       * 为 dynamic imports 启用 lazy compilation
+       */
+      imports?: boolean;
+      /**
+       * 指定哪些导入的模块应该被延迟编译
+       */
+      test?: RegExp | ((m: Module) => boolean);
+      /**
+       * 指定一个自定义的运行时代码路径，用于覆盖默认的 lazy compilation client
+       */
+      client?: string;
+      /**
+       * 指定 client 需要请求的 server URL
+       */
+      serverUrl?: string;
+    };
+```
+
+- **默认值：** `false`
+
+用于开启 lazy compilation（即按需编译），基于 Rspack 的 [lazy compilation](https://rspack.rs/zh/guide/features/lazy-compilation) 特性实现。
+
+import RsbuildLink from '@site/src/components/RsbuildLink';
+
+:::info
+该配置项的使用方式与 Rsbuild 完全一致，详细信息可参考 <RsbuildLink configName="dev.lazyCompilation"/>。
+:::

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

@@ -0,0 +1,211 @@
+---
+title: server
+---
+
+# dev.server
+
+- **类型：** `Object`
+- **默认值：** `{}`
+
+通过 `dev.server` 可以修改开发环境服务器的配置。
+
+### compress
+
+- **类型：** `boolean`
+- **默认值：** `true`
+
+是否对静态资源启用 gzip 压缩。
+
+如果你需要禁用 gzip 压缩，可以将 `compress` 设置为 `false`：
+
+```ts
+export default {
+  dev: {
+    server: {
+      compress: false,
+    },
+  },
+};
+```
+
+更多详细信息请参考 [Rsbuild - server.compress](https://rsbuild.rs/zh/config/server/compress) 文档。
+
+### headers
+
+- **类型：** `Record<string, string>`
+- **默认值：** `undefined`
+
+设置自定义响应头。
+
+```js
+export default {
+  dev: {
+    server: {
+      headers: {
+        'X-Custom-Foo': 'bar',
+      },
+    },
+  },
+};
+```
+
+更多详细信息请参考 [Rsbuild - server.headers](https://rsbuild.rs/zh/config/server/headers) 文档。
+
+### historyApiFallback
+
+- **类型：** `boolean | ConnectHistoryApiFallbackOptions`
+- **默认值：** `false`
+
+在需要对一些 404 响应或其他请求提供替代页面的场景，可通过 `dev.server.historyApiFallback` 进行设置：
+
+```js
+export default {
+  dev: {
+    server: {
+      historyApiFallback: true,
+    },
+  },
+};
+```
+
+更多配置选项请参考 [Rsbuild - server.historyApiFallback](https://rsbuild.rs/zh/config/server/history-api-fallback) 文档。
+
+### watch
+
+- **类型：** `boolean`
+- **默认值：** `true`
+
+是否监听 `mock/`、`server/`、`api/` 等目录的文件变化。
+
+更多详细信息请参考 [Rsbuild - dev.watchFiles](https://rsbuild.rs/zh/config/dev/watch-files) 文档。
+
+### cors
+
+- **类型:** `boolean | import('cors').CorsOptions`
+
+为开发服务器配置 CORS（跨域资源共享）。
+
+Modern.js 中 `cors` 的默认配置遵循 Rsbuild 的默认值：
+
+```ts
+const defaultAllowedOrigins =
+  /^https?:\/\/(?:(?:[^:]+\.)?localhost|127\.0\.0\.1|\[::1\])(?::\d+)?$/;
+
+const defaultOptions = {
+  // 默认允许：
+  // - localhost
+  // - 127.0.0.1
+  // - [::1]
+  origin: defaultAllowedOrigins,
+};
+```
+
+更多配置选项和详细用法请参考 [Rsbuild - server.cors](https://rsbuild.rs/zh/config/server/cors) 文档。
+
+### proxy
+
+- **类型：** `Record<string, string> | Record<string, ProxyDetail>`
+- **默认值：** `undefined`
+
+代理请求到指定的服务上。
+
+```js
+export default {
+  dev: {
+    server: {
+      proxy: {
+        '/api': 'http://localhost:3000',
+      },
+    },
+  },
+};
+```
+
+此时，/api/users 请求将会代理到 http://localhost:3000/api/users。
+
+如果你不想传递 /api，可以通过 `pathRewrite` 重写请求路径：
+
+```js
+export default {
+  dev: {
+    server: {
+      proxy: {
+        '/api': {
+          target: 'http://localhost:3000',
+          pathRewrite: { '^/api': '' },
+        },
+      },
+    },
+  },
+};
+```
+
+DevServer Proxy 基于 [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware/tree/2.x) 实现。你可以使用 http-proxy-middleware 的所有配置项，具体可以查看文档。
+
+DevServer Proxy 完整类型定义为：
+
+```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;
+```
+
+除了 http-proxy-middleware 的选项外，还支持 bypass 和 context 两个配置项：
+
+- bypass：根据函数的返回值绕过代理。
+  - 返回 `null` 或 `undefined` 会继续用代理处理请求。
+  - 返回 `false` 会返回 404 错误。
+  - 返回一个具体的服务路径，将会使用此路径替代原请求路径。
+- context：如果你想代理多个特定的路径到同一个目标，你可以使用 context 配置项。
+
+```js
+// 自定义 bypass 方法
+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
+// 代理多个路径到同一个目标
+export default {
+  dev: {
+    server: {
+      proxy: [
+        {
+          context: ['/auth', '/api'],
+          target: 'http://localhost:3000',
+        },
+      ],
+    },
+  },
+};
+```

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

@@ -7,32 +7,13 @@ title: setupMiddlewares
 - **类型：**
 
 ```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]: {
-      /**
-       * 获取当前环境的构建信息
-       */
-      getStats: () => Promise<Stats>;
-
-      /**
-       * 在服务端加载并执行构建产物
-       *
-       * @param entryName - 入口名称，和 Rsbuild source.entry 的某一个 key 值对应
-       * @returns 入口模块的返回值
-       */
-      loadBundle: <T = unknown>(entryName: string) => Promise<T>;
-
-      /**
-       * 获取编译后的 HTML 模版内容
-       */
-      getTransformedHtml: (entryName: string) => Promise<string>;
-    };
-  };
 };
 
 type SetupMiddlewares = Array<
@@ -41,7 +22,7 @@ type SetupMiddlewares = Array<
       unshift: (...handlers: RequestHandler[]) => void;
       push: (...handlers: RequestHandler[]) => void;
     },
-    server: SetupMiddlewaresServer,
+    server: ExposeServerApis,
   ) => void
 >;
 ```

package/docs/zh/configure/app/experiments/source-build.mdx

@@ -6,7 +6,6 @@ title: sourceBuild
 
 - **类型：** `boolean | PluginSourceBuildOptions`
 - **默认值：** `false`
-- **版本：** `MAJOR_VERSION.46.0`
 
 用于开启源码构建的能力。当开启此配置项时，Modern.js 会读取子项目 package.json 的 `source` 字段对应的源码文件，并进行编译。
 

package/docs/zh/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 @@ type AppIcon = string | {
 - 生成 web app manifest 文件和其中的 `icons` 字段。
 - 生成 HTML 文件中的 `apple-touch-icon` 标签和 `manifest` 标签。
 
-### 字符串形式
-
-`string` 类型的 `appIcon` 配置是对象类型的一个语法糖。
-
-```js
-export default {
-  html: {
-    appIcon: './src/assets/icon.png',
-  },
-};
-```
-
-以上配置相当于下面配置的语法糖：
-
-```js
-export default {
-  html: {
-    appIcon: { icons: [{ src: './src/assets/icon.png', size: 180 }] }
-  },
-};
-```
-
 import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
 
 <RsbuildConfig configName="html.appIcon" />

package/docs/zh/configure/app/output/assets-retry.mdx

@@ -31,7 +31,7 @@ export type AssetsRetryOptions = {
 
 - **默认值：** `undefined`
 
-由于该能力会往 HTML 中和 [webpack/Rspack Runtime](https://rspack.rs/api/runtime-api/module-variables) 注入额外的一些运行时代码，因此我们默认关闭了该能力，如果需要开启该能力，你可以添加以下配置：
+由于该能力会往 HTML 中和 [Rspack Runtime](https://rspack.rs/api/runtime-api/module-variables) 注入额外的一些运行时代码，因此我们默认关闭了该能力，如果需要开启该能力，你可以添加以下配置：
 
 ```js
 export default {

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

@@ -10,9 +10,9 @@ title: disableInlineRuntimeChunk
 用于控制是否将打包工具的 runtime 代码内联到 HTML 中。
 
 :::tip 什么是 runtimeChunk
-当构建完成后，会在 dist 目录生成 `builder-runtime.js` 文件，该文件为 webpack 或 Rspack 的 runtime 代码，即 runtimeChunk。
+当构建完成后，会在 dist 目录生成 `builder-runtime.js` 文件，该文件为 Rspack 的 runtime 代码，即 runtimeChunk。
 
-runtimeChunk 是一段运行时代码，它由 webpack 或 Rspack 提供，包含必要的模块处理逻辑，比如模块加载、模块解析等，具体可参考 [Runtime](https://webpack.js.org/concepts/manifest/#runtime)。
+runtimeChunk 是一段运行时代码，它由 Rspack 提供，包含必要的模块处理逻辑，比如模块加载、模块解析等，具体可参考 [Runtime Chunk](https://rspack.rs/config/optimization#optimizationruntimechunk)。
 
 :::
 

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

@@ -2,16 +2,14 @@
 title: filename
 ---
 
+# output.filename
+
 :::warning
 
 在 Modern.js 开发阶段，或是使用 Modern.js 服务器部署应用时，应避免使用该配置修改 html 产物文件名，会导致页面 404。
 
-通常情况下，无需修改 html 产物文件名。常见的需求是将 `main.html` 修改为 `index.html`，请使用 [source.mainEntryName](/configure/app/source/main-entry-name)。
-
 :::
 
-# output.filename
-
 - **类型：**
 
 ```ts

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

@@ -20,7 +20,7 @@ type InlineScripts =
     };
 ```
 
-- **默认值：** `false`
+- **默认值：** `/builder-runtime([.].+)?\.js$/`
 
 用来控制是否用 `<script>` 标签将产物中的 script 文件（.js 文件）inline 到 HTML 中。
 

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

@@ -9,9 +9,9 @@ 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'],
 };
 ```
 
@@ -19,7 +19,7 @@ const defaultBrowserListMap: Record<RsbuildTarget, string[]> = {
 
 该值会被 [SWC](https://github.com/swc-project/swc) 和 [autoprefixer](https://github.com/postcss/autoprefixer) 用来确定需要转换的 JavaScript 语法特性和需要添加的 CSS 浏览器前缀。
 
-Modern.js 会优先使用项目根目录的 `.browserslistrc` 文件中的配置。
+其他配置方式和配置优先级请参考 [Browserslist 配置](/guides/advanced-features/compatibility.html)。
 
 import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
 

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

@@ -15,17 +15,24 @@ type SourceMap =
     };
 ```
 
+用于设置是否生成 source map 文件，以及生成哪一种格式的 source map。
+
 - **默认值：**
 
 ```ts
 const defaultSourceMap = {
-  js: isDev ? 'cheap-module-source-map' : false,
-  css: false,
+  js: isDev ? 'cheap-module-source-map' : 'hidden-source-map',
+  css: isDev,
 };
 ```
 
-用于设置是否生成 source map 文件，以及生成哪一种格式的 source map。
+在不配置 `output.sourceMap` 时，Modern.js 的 source map 生成规则与 Rsbuild 配置有差异：
+
+- 在开发模式构建时，会生成 JS 文件和 CSS 的 source map，便于进行开发调试。
+- 在生产模式构建时，会生成 JS 的 source map 用于堆栈回溯，不生成 CSS 文件的 source map，以提供最佳的构建性能。
 
 import RsbuildConfig from '@site-docs/components/rsbuild-config-tooltip';
 
 <RsbuildConfig configName="output.sourceMap" />
+
+