@modern-js/main-doc 2.40.0 → 2.42.0

package/docs/en/guides/troubleshooting/hmr.mdx

@@ -0,0 +1,148 @@
+---
+sidebar_position: 4
+---
+
+# HMR FAQ
+
+### How to troubleshooting HMR ineffective issues?
+
+There are several possible reasons why HMR may not be work. This document will cover most common causes and provide guidance for troubleshooting. Please refer to the following content for troubleshooting.
+
+Before starting the troubleshooting process, it is helpful to have a basic understanding of how HMR works:
+
+:::tip HMR Principle
+
+1. The browser establishes a WebSocket connection with the development server for real-time communication.
+2. Whenever the development server finishes recompiling, it sends a notification to the browser via the WebSocket. The browser then sends a `hot-update.xxx` request to the development server to load the newly compiled module.
+3. After receiving the new module, if it is a React project, React Refresh, an official React tool, is used to update React components. Other frameworks have similar tools.
+
+:::
+
+After understanding the principle of HMR, you can follow these steps for basic troubleshooting:
+
+#### 1. Check the WebSocket Connection
+
+Open the browser console and check for the presence of the `[HMR] connected.` log.
+
+- If it is present, the WebSocket connection is working correctly. You can continue with the following steps.
+- If it is not present, open the Network panel in Chrome and check the status of the `ws://[host]:[port]/webpack-hmr` request. If the request is failed, this indicates that the HMR failed because the WebSocket connection was not successfully established.
+
+There can be various reasons why the WebSocket connection fails to establish, such as using a network proxy that prevents the WebSocket request from reaching the development server. You can check whether the WebSocket request address matches your development server address. If it does not match, you can configure the WebSocket request address using [tools.devServer.client](/configure/app/tools/dev-server.html#client).
+
+#### 2. Check the hot-update Requests
+
+When you modify the code of a module and trigger a recompilation, the browser sends several `hot-update.json` and `hot-update.js` requests to the development server to fetch the updated code.
+
+You can try modifying a module and inspect the content of the `hot-update.xxx` requests. If the content of the request is the latest code, it indicates that the hot update request is working correctly.
+
+If the content of the request is incorrect, it is likely due to a network proxy. Check whether the address of the `hot-update.xxx` request matches your development server address. If it does not match, you need to adjust the proxy rules to route the `hot-update.xxx` request to the development server address.
+
+#### 3. Check for Other Causes
+
+If the above two steps do not reveal any issues, it is possible that other factors are causing the HMR to fail. For example, it could be that the code does not meet React's requirements for HMR. You can refer to the following questions for further troubleshooting.
+
+---
+
+### HMR not working when external React?
+
+To ensure that HMR works properly, we need to use the development builds of React and ReactDOM.
+
+If you exclude React via `externals` when bundling, the production build of React is usually injected through CDN, and this can cause HMR to fail.
+
+```js
+export default {
+  output: {
+    externals: {
+      react: 'React',
+      'react-dom': 'ReactDOM',
+    },
+  },
+};
+```
+
+To solve this problem, you need to reference the development builds of React or not configure `externals` in the development environment.
+
+If you are unsure about the type of React build you are using, you can refer to the [React documentation - Use the Production Build](https://legacy.reactjs.org/docs/optimizing-performance.html#use-the-production-build).
+
+---
+
+### HMR not working when setting filename hash in development mode?
+
+Usually, we only set the filename hash in the production mode (i.e., when `process.env.NODE_ENV === 'production'`).
+
+If you set the filename hash in the development mode, it may cause HMR to fail (especially for CSS files). This is because every time the file content changes, the hash value changes, preventing tools like [mini-css-extract-plugin](https://www.npmjs.com/package/mini-css-extract-plugin) from reading the latest file content.
+
+- Correct usage:
+
+```js
+export default {
+  output: {
+    filename: {
+      css:
+        process.env.NODE_ENV === 'production'
+          ? '[name].[contenthash:8].css'
+          : '[name].css',
+    },
+  },
+};
+```
+
+- Incorrect usage:
+
+```js
+export default {
+  output: {
+    filename: {
+      css: '[name].[contenthash:8].css',
+    },
+  },
+};
+```
+
+---
+
+### HMR not working when updating React components?
+
+Modern.js uses React's official [Fast Refresh](https://github.com/pmmmwh/react-refresh-webpack-plugin) capability to perform component hot updates.
+
+If there is a problem that the hot update of the React component cannot take effect, or the state of the React component is lost after the hot update, it is usually because your React component uses an anonymous function. In the official practice of React Fast Refresh, it is required that the component cannot be an anonymous function, otherwise the state of the React component cannot be preserved after hot update.
+
+Here are some examples of wrong usage:
+
+```tsx
+// bad
+export default function () {
+  return <div>Hello World</div>;
+}
+
+// bad
+export default () => <div>Hello World</div>;
+```
+
+The correct usage is to declare a name for each component function:
+
+```tsx
+// good
+export default function MyComponent() {
+  return <div>Hello World</div>;
+}
+
+// good
+const MyComponent = () => <div>Hello World</div>;
+
+export default MyComponent;
+```
+
+---
+
+### HMR not working when use https?
+
+If https is enabled, the HMR connection may fail due to a certificate issue, and if you open the console, you will get an HMR connect failed error.
+
+![hmr-connect-error-0](https://lf3-static.bytednsdoc.com/obj/eden-cn/6221eh7uhbfvhn/modern/img_v2_2f90d027-a232-4bd8-8021-dac3c651682g.jpg)
+
+The solution to this problem is to click on "Advanced" -> "Proceed to xxx (unsafe)" on the Chrome problem page.
+
+![hmr-connect-error-1](https://lf3-static.bytednsdoc.com/obj/eden-cn/6221eh7uhbfvhn/modern/3d2d4a38-acfe-4fe2-bdff-48b3366db481.png)
+
+> Tips: When accessing the page through Localhost, the words "Your connection is not private" may not appear and can be handled by visiting the Network domain.

package/docs/zh/apis/app/commands.mdx

@@ -278,7 +278,9 @@ Options:
 Usage: modern test [options]
 
 Options:
-  -h, --help  显示命令帮助
+  -u --updateSnapshot  使用此选项来更新快照
+  --watch              监视文件的变更并重新运行相关的测试
+  -h, --help           显示命令帮助
 ```
 
 :::tip

package/docs/zh/community/contributing-guide.mdx

@@ -177,6 +177,16 @@ pnpm run lint
 
 ---
 
+## Benchmarking
+
+你可以在 PR 的评论区中输入 `!bench-framework` 或 `!bench-module` 分别对 `@modern-js/app-tools` 和 `@modern-js/module-tools` 做性能测试（这需要你具有 Collaborator 及以上的权限）。
+
+你可以根据评论输出的对比表格，重点关注构建时间和产物体积相关的指标，辅助进行相关性能判断与决策。
+
+依赖安装相关指标由于需要前置的发包流程，因此数据相对有滞后性，仅供参考。
+
+---
+
 ## 文档
 
 目前 Modern.js 提供英文和中文文档。如果你熟悉中文，请同时更新中英文文档。否则，只需更新英文文档即可。

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

@@ -1,21 +1,21 @@
 ---
-sidebar_label: enableInlineRouteManifests
+sidebar_label: disableInlineRouteManifests
 ---
 
-# output.enableInlineRouteManifests
+# output.disableInlineRouteManifests
 
 - **类型:** `boolean`
-- **默认值:** `true`
+- **默认值:** `false`
 
 当使用约定式路由时，框架为了做一些优化，会向客户端中注入路由信息，默认情况下路由信息会注入到 html 中，
-当该配置为 `false` 时，路由信息会注入到一个单独的 JS 文件中。
+当该配置为 `true` 时，路由信息会注入到一个单独的 JS 文件中。
 
 Example:
 
 ```ts
 export default {
   output: {
-    enableInlineRouteManifests: false,
+    disableInlineRouteManifests: true,
   },
-}
+};
 ```

package/docs/zh/configure/app/tools/bundler-chain.mdx

@@ -4,10 +4,6 @@ sidebar_label: bundlerChain
 
 # tools.bundlerChain
 
-:::tip
-该配置由 Modern.js Builder 提供，更多信息可参考 [tools.bundlerChain](https://modernjs.dev/builder/api/config-tools.html#toolsbundlerchain)。
-:::
-
 import Main from '@modern-js/builder-doc/docs/zh/config/tools/bundlerChain.mdx';
 
 <Main />

package/docs/zh/guides/advanced-features/build-performance.mdx

@@ -0,0 +1,156 @@
+---
+sidebar_position: 12
+---
+
+# 提升构建性能
+
+Modern.js 默认对构建性能进行了充分优化，但是随着业务场景变复杂、项目代码量变大，你可能会遇到一些构建性能的问题。
+
+本文档提供了一些可选的提速策略，**开发者可以根据实际场景选取其中的部分策略**，从而进一步提升构建速度。
+
+:::tip 📢 注意
+在[优化产物体积](/guides/advanced-features/optimize-bundle.html)一文中介绍的策略也可以用于提升构建性能，这里不再重复介绍。
+:::
+
+## 通用优化策略
+
+以下是一些通用的优化策略，对开发环境和生产环境均有提速效果，其中部分策略对包体积也有优化。
+
+### 升级 Node.js 版本
+
+通常来说，将 Node.js 更新到最新的 [LTS 版本](https://github.com/nodejs/release#release-schedule)，有助于提升构建性能。
+
+尤其是对于 Apple M1/M2 芯片的机型，推荐使用 Node 18 进行构建。
+
+Node >= 16 默认提供了 Apple Silicon binaries，因此在 M1/M2 机型上性能会比 Node 14 有大幅度提升。根据我们的测试，**从 Node 14 切换到 Node >= 16 后，编译速度可以提升 100% 以上**。
+
+你可以通过以下步骤来切换到 Node 18：
+
+```bash
+# 安装 Node v18
+nvm install 18
+
+# 切换到 Node 18
+nvm use 18
+
+# 将 Node 18 设置为默认版本
+nvm default 18
+
+# 查看 Node 版本
+node -v
+```
+
+### 使用 Rspack 构建
+
+如果你对构建性能有更极致的需求，可以一键切换到 Rspack 构建模式，请参考 [使用 Rspack](/guides/advanced-features/rspack-start.html) 来进行切换。
+
+### 使用 SWC 或 esbuild 编译
+
+[SWC](https://swc.rs/) (Speedy Web Compiler) 是基于 `Rust` 语言编写的高性能 JavaScript 和 TypeScript 转译和压缩工具。在 Polyfill 和语法降级方面可以和 Babel 提供一致的能力，并且性能比 Babel 高出一个数量级。
+
+[esbuild](https://esbuild.github.io/) 是一款基于 Golang 开发的前端构建工具，具有打包、编译和压缩 JavaScript 代码的功能，相比传统的打包编译工具，esbuild 在性能上有显著提升。
+
+Modern.js 提供了 SWC 插件和 esbuild 插件，让你能使用 SWC 或 esbuild 代替 babel-loader、ts-loader 和 terser 等库进行代码编译和压缩。详见：
+
+- [SWC 插件文档](/configure/app/tools/swc.html)
+- [esbuild 插件文档](/configure/app/tools/esbuild.html)
+
+:::tip SWC vs esbuild
+SWC 编译产物的兼容性较好，支持注入 core-js 等 Polyfill，并且功能更加完备，因此推荐优先使用 SWC 插件。
+:::
+
+### 避免使用 ts-loader
+
+默认情况下，Modern.js 使用 Babel 编译 TS 文件，开启 [tools.tsLoader](/configure/app/tools/ts-loader.html) 选项后，会使用 `ts-loader` 编译 TS 文件。
+
+由于 `ts-loader` 需要进行额外的语法解析和类型检查，因此会导致项目构建速度变慢，请避免使用。
+
+```js
+export default {
+  tools: {
+    // 移除这项配置
+    tsLoader: {},
+  },
+};
+```
+
+详见 [tools.tsLoader 文档](/configure/app/tools/ts-loader.html)。
+
+## 开发环境优化策略
+
+以下是针对开发环境进行提速的策略。
+
+### 调整 Source Map 格式
+
+为了提供良好的调试体验，Modern.js 在开发环境下默认使用 `cheap-module-source-map` 格式 Source Map，这是一种高质量的 Source Map 格式，会带来一定的性能开销。
+
+你可以通过调整开发环境的 Source Map 格式来提升构建速度。
+
+比如禁用 Source Map：
+
+```js
+export default {
+  tools: {
+    bundlerChain(chain, { env }) {
+      if (env === 'development') {
+        chain.devtool(false);
+      }
+    },
+  },
+};
+```
+
+或是把开发环境的 Source Map 格式设置为开销最小的 `eval` 格式：
+
+```js
+export default {
+  tools: {
+    bundlerChain(chain, { env }) {
+      if (env === 'development') {
+        chain.devtool('eval');
+      }
+    },
+  },
+};
+```
+
+> 关于不同 Source Map 格式之间的详细差异，请查看 [webpack - devtool](https://webpack.js.org/configuration/devtool/)。
+
+### 调整 Browserslist 范围
+
+这项优化的原理与[「提升 Browserslist 范围」](/guides/advanced-features/optimize-bundle.html#adjust-browserslist)类似，区别在于，我们可以为开发环境和生产环境设置不同的 browserslist，从而减少开发环境下的编译开销。
+
+比如，你可以在 `package.json` 中添加以下配置，表示在开发环境下只兼容最新的浏览器，在生产环境下兼容实际需要的浏览器：
+
+```json
+{
+  "browserslist": {
+    "production": [">0.2%", "not dead", "not op_mini all"],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  }
+}
+```
+
+注意，这项优化策略会导致开发环境与生产环境的构建产物存在一定差异。
+
+## 生产环境优化策略
+
+以下是针对生产环境进行提速的策略。
+
+### 禁用 Source Map
+
+如果项目在生产环境下不需要 Source Map，可以通过 `disableSourceMap` 配置项关闭，从而提升 build 构建的速度。
+
+```js
+export default {
+  output: {
+    disableSourceMap: true,
+  },
+};
+```
+
+详见 [output.disableSourceMap](/configure/app/output/disable-source-map.html)。

package/docs/zh/guides/advanced-features/optimize-bundle.mdx

@@ -0,0 +1,115 @@
+---
+sidebar_position: 13
+---
+
+# 产物体积优化
+
+产物体积的优化在生产环境中是非常重要的，因为它直接影响到了线上的用户体验。在这篇文档中，我们将介绍在 Builder 中一些常见的产物体积优化方式。
+
+## 减少重复依赖
+
+在业务项目中，会存在某些第三方依赖被安装了多个版本的现象。重复依赖会导致包体积变大、构建速度变慢。
+
+我们可以通过社区中的一些工具来检测或消除重复依赖。
+
+- 如果你在使用 `pnpm >= 7.26.0`，可以使用 pnpm 自带的 [pnpm dedupe](https://pnpm.io/cli/dedupe) 命令来升级和消除其中的重复依赖。
+
+```bash
+pnpm dedupe
+```
+
+- 如果你在使用 `pnpm < 7.26.0` 版本，可以使用 [pnpm-deduplicate](https://github.com/ocavue/pnpm-deduplicate) 来分析出所有的重复依赖，并通过升级依赖或声明 [pnpm overrides](https://pnpm.io/package_json#pnpmoverrides) 进行版本合并。
+
+```bash
+npx pnpm-deduplicate --list
+```
+
+- 如果你在使用 `yarn`，可以使用 [yarn-deduplicate](https://github.com/scinos/yarn-deduplicate) 来自动合并重复依赖：
+
+```bash
+npx yarn-deduplicate && yarn
+```
+
+## 使用更轻量的库
+
+建议将项目中体积较大的三方库替换为更轻量的库，比如将 [moment](https://momentjs.com/) 替换为 [day.js](https://day.js.org/)。
+
+如果你需要找出项目中体积较大的三方库，可以在执行构建时添加 `BUNDLE_ANALYZE=true` 环境变量：
+
+```bash
+BUNDLE_ANALYZE=true pnpm build
+```
+
+详见 [performance.bundleAnalyze](/configure/app/performance/bundle-analyze.html) 配置项。
+
+## 提升 Browserslist 范围
+
+Builder 会根据项目的 Browserslist 配置范围进行代码编译，并注入相应的 Polyfill。如果项目不需要兼容旧版浏览器，可以根据实际情况来提升 Browserslist 范围，从而减少在语法和 Polyfill 上的编译开销。
+
+Builder 默认的 Browserslist 配置为：
+
+```js
+['> 0.01%', 'not dead', 'not op_mini all'];
+```
+
+比如只兼容 Chrome 61 以上的浏览器，可以改成：
+
+```js
+['Chrome >= 61'];
+```
+
+:::tip
+请阅读 [设置浏览器范围](https://modernjs.dev/builder/guide/advanced/browserslist.html) 章节来了解更多关于 Browserslist 的用法。
+:::
+
+## 按需引入 polyfill
+
+在明确第三方依赖不需要额外 polyfill 的情况下，你可以将 [output.polyfill](/configure/app/output/polyfill.html) 设置为 `usage`。
+
+在 `usage` 模式下，Builder 会分析源代码中使用的语法，按需注入所需的 polyfill 代码，从而减少 polyfill 的代码量。
+
+```js
+export default {
+  output: {
+    polyfill: 'usage',
+  },
+};
+```
+
+:::tip
+请阅读 [浏览器兼容性](https://modernjs.dev/builder/guide/advanced/browser-compatibility.html) 章节来了解更多关于 polyfill 的用法。
+:::
+
+## 使用图片压缩
+
+在一般的前端项目中，图片资源的体积往往是项目产物体积的大头，因此如果能尽可能精简图片的体积，那么将会对项目的打包产物体积起到明显的优化效果。你可以在 Builder 中注册插件来启用图片压缩功能:
+
+```js
+import { builderPluginImageCompress } from '@modern-js/builder-plugin-image-compress';
+
+// 往 builder 实例上添加插件
+builder.addPlugins([builderPluginImageCompress()]);
+```
+
+详见 [Image Compress 插件](https://modernjs.dev/builder/plugins/plugin-image-compress.html)。
+
+## 代码拆包
+
+良好的拆包策略对于提升应用的加载性能是十分重要的，可以充分利用浏览器的缓存机制，减少请求数量，加快页面加载速度。
+
+在 Builder 中内置了[多种拆包策略](https://modernjs.dev/builder/guide/optimization/split-chunk)，可以满足大部分应用的需求，你也可以根据自己的业务场景，自定义拆包配置。
+
+比如将 node_modules 下的 `axios` 库拆分到 `axios.js` 中：
+
+```js
+export default {
+  performance: {
+    chunkSplit: {
+      strategy: 'split-by-experience',
+      forceSplitting: {
+        axios: /node_modules\/axios/,
+      },
+    },
+  },
+};
+```

package/docs/zh/guides/advanced-features/rspack-start.mdx

@@ -83,7 +83,7 @@ import RspackPrecautions from '@modern-js/builder-doc/docs/zh/shared/rspackPreca
   "pnpm": {
     "overrides": {
       "@rspack/core": "nightly",
-      "@rspack/dev-client": "nightly",
+      "@rspack/plugin-react-refresh": "nightly",
       "@rspack/plugin-html": "nightly"
     }
   }

package/docs/zh/guides/advanced-features/source-build.mdx

@@ -0,0 +1,161 @@
+---
+sidebar_position: 11
+---
+
+# 源码构建模式
+
+源码构建模式用于 monorepo 开发场景，它允许开发者直接引用 monorepo 中其他子项目的源码进行开发。
+
+## 使用场景
+
+**monorepo 中项目互相引用主要有产物引用和源码引用两种方式**。我们以一个最简单的 monorepo 为例子，来介绍源码引用的使用场景。
+
+比如 monorepo 中包含了一个 app 应用和一个 lib 包：
+
+```ts
+monorepo
+├── app
+└── lib
+    └── src
+        └── index.ts
+```
+
+其中，app 是基于 Modern.js 构建的，app 依赖了 lib 中的一些方法：
+
+```json
+{
+  "name": "app",
+  "dependencies": {
+    "lib": "workspace:*"
+  }
+}
+```
+
+### 产物引用
+
+**产物引用指的是当前项目引用其他子项目构建后的产物。**
+
+比如上述例子中的 lib 是使用 TypeScript 编写的，通常情况下，我们需要提前构建 lib 的代码，生成 JavaScript 产物，这样 app 才可以正确引用它。当 lib 代码更新时，还需要重新执行一次构建（或者使用 `tsc --watch`），否则 app 无法引用到最新的代码。
+
+这种方式的优势在于：
+
+- 各个子项目的构建过程是完全独立的，可以拥有不同的构建配置。
+- 可以针对子项目进行构建缓存。
+
+劣势在于：
+
+- 本地开发时 HMR 的链路变长。
+- 当一个项目中包含多个 lib 包时，以上过程会显得十分繁琐。
+
+### 源码引用
+
+**源码引用指的是当前项目引用其他子项目的源码进行构建。**
+
+比如上述例子，当你开启了源码构建模式，并在 lib 中添加相关配置后，Modern.js 会自动引用 lib 的 `src/index.ts` 源代码。这意味着，你不需要提前构建 lib 的代码，并且当 lib 的源代码更新时，也可以自动触发 app 的热更新。
+
+这种方式的优势在于：
+
+- 子项目不依赖构建工具，也不需要添加构建配置，子项目的代码会被当前项目的构建工具编译。
+- 不需要提前执行子项目的构建流程。
+- 本地开发时 HMR 更高效。
+
+劣势在于：
+
+- 当前项目需要支持子项目用到的语法特性，并且遵循相同的语法规范，比如使用一致的装饰器语法版本。如果当前项目和子项目需要使用不同的编译配置，则不适合使用源码构建。
+- 当前项目需要编译更多的代码，因此构建时间可能会变长。
+
+## 使用源码构建
+
+### 开启配置
+
+你可以通过设置 [experiments.sourceBuild](/configure/app/experiments/source-build.html) 为 `true` 来开启源码构建模式。
+
+```ts
+export default {
+  experiments: {
+    sourceBuild: true,
+  },
+};
+```
+
+### 配置子项目
+
+当开启源码构建模式后，Modern.js 在构建过程中，会优先读取子项目的 `source` 字段对应的文件。因此，你需要在子项目的 package.json 中配置 `source` 字段，并且指向源码文件路径。
+
+比如以下例子，当 lib 包被引用时，会读取 `./src/index.ts` 文件进行构建：
+
+```json title="package.json"
+{
+  "name": "lib",
+  "main": "./dist/index.js",
+  "source": "./src/index.ts"
+}
+```
+
+如果子项目使用了 [exports](https://nodejs.org/api/packages.html#package-entry-points) 配置，那么你同样需要在 `exports` 中增加 `source` 字段。
+
+```json title="package.json"
+{
+  "name": "lib",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./features": {
+      "source": "./src/features/index.ts",
+      "default": "./dist/features/index.js"
+    }
+  }
+}
+```
+
+## 配置 Project Reference
+
+在 TypeScript 项目中，你需要使用 TypeScript 提供的 [Project Reference](https://www.typescriptlang.org/docs/handbook/project-references.html) 能力，它可以帮助你更好地使用源码开发。
+
+### 介绍
+
+Project reference 提供了以下能力：
+
+- 使 TypeScript 可以正确识别其他子项目的类型，而无须对子项目进行构建。
+- 当你在 VS Code 内进行代码跳转时，VS Code 可以自动跳转到对应模块的源代码文件。
+- Modern.js 会读取 project reference 配置，并自动识别子项目的 `tsconfig.compilerOptions.path` 配置，从而让子项目的别名可以正确生效。
+
+### 示例
+
+在上文的例子中，由于 app 引用了 lib 子项目，我们需要在 app 的 `tsconfig.json` 内配置 `composite` 和 `references`，并指向 lib 对应的相对目录：
+
+```json title="app/tsconfig.json"
+{
+  "compilerOptions": {
+    "composite": true
+  },
+  "references": [
+    {
+      "path": "../lib"
+    }
+  ]
+}
+```
+
+添加以上两个选项后，project reference 就已经配置完成了，你可以重新启动 VS Code 来查看配置以后的效果。
+
+注意以上只是一个最简单的例子，在实际的 monorepo 项目中，可能会有更复杂的依赖关系，你需要添加完整的 `references` 配置，才能使上述功能正确运作。
+
+:::tip
+如果你想了解更多关于 project reference 的内容，请阅读 [TypeScript - Project References](https://www.typescriptlang.org/docs/handbook/project-references.html) 官方文档。
+:::
+
+## 注意事项
+
+在使用源码构建模式的时候，需要注意几点：
+
+1. 需要保证当前项目可以编译子项目里使用的语法或特性。比如子项目使用了 Stylus 来编写 CSS 样式，那就需要当前 app 支持 Stylus 编译。
+2. 需要保证当前项目与子项目使用的代码语法特性相同，例如装饰器的语法版本一致。
+3. 源码构建可能存在一些限制。如果在使用中遇到问题，你可以将子项目 package.json 中的 `source` 字段移除，使用子项目的构建产物进行调试。
+4. 开启 `composite: true` 后，TypeScript 会生成 `*.tsbuildinfo` 临时文件，你需要将这些临时文件加入 .gitignore 中。
+
+```text title=".gitignore"
+*.tsbuildinfo
+```

package/docs/zh/guides/advanced-features/testing.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 11
+sidebar_position: 14
 ---
 
 # 使用 Jest 测试

package/docs/zh/guides/advanced-features/using-storybook.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 12
+sidebar_position: 15
 ---
 
 # 使用 StorybookV6

package/docs/zh/guides/advanced-features/web-server.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 13
+sidebar_position: 16
 ---
 
 # 自定义 Web Server