@modern-js/main-doc 2.2.0 → 2.3.0

package/zh/configure/app/tools/webpack.mdx

@@ -1,10 +1,11 @@
 ---
-title: tools.webpack
 sidebar_label: webpack
 ---
 
-:::info BUILDER
-该配置为 Modern.js Builder 配置，详细信息可参考 [tools.webpack](https://modernjs.dev/builder/api/config-tools.html#tools-webpack)。
+# tools.webpack
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [tools.webpack](https://modernjs.dev/builder/api/config-tools.html#tools-webpack)。
 :::
 
 import Main from '@modern-js/builder-doc/docs/zh/config/tools/webpack.md'

package/zh/configure/app/usage.mdx

@@ -8,22 +8,22 @@ Modern.js 中有两种配置，一个是编译时配置，一个是服务端运
 
 编译时配置可以在两个位置进行配置：
 
+- 根路径下的 `modern.config.(ts|js|mjs)` 文件
 - `package.json` 文件
-- 根路径下的 `modern.config.t(j)s` 文件
-
-:::warning 注意
-同一个配置不支持同时在 `package.json` 中和 `modern.config.t(j)s` 中配置。推荐在 `modern.config.t(j)s` 中进行配置。
 
+:::info
+不支持同时在 package.json 中和 modern.config.ts 中配置同一个配置项，推荐优先在 modern.config.ts 中进行配置。如果 Modern.js 检测到重复配置导致的冲突，将会抛出警告。
 :::
 
-服务端运行时配置可以在根路径下的 `modern.server-runtime.config.t(j)s` 自定义配置选项。
+服务端运行时配置可以在根路径下的 `modern.server-runtime.config.(ts|js|mjs)` 中自定义配置选项。
 
 ## 在配置文件中配置
 
-Modern.js 的配置文件定义在项目的根目录下，同时支持 `.js` 和 `.ts` 两种格式：
+Modern.js 的配置文件定义在项目的根目录下，支持 `.js`, `.ts` 和 `.mjs` 格式：
 
 - `modern.config.js`
 - `modern.config.ts`
+- `modern.config.mjs`
 
 ### modern.config.js
 
@@ -51,7 +51,7 @@ export default {
 };
 ```
 
-### modern.config.ts
+### modern.config.ts（推荐）
 
 我们推荐使用 .ts 格式的配置文件，它提供了友好的 TypeScript 类型提示，从而帮助你避免配置中的错误。
 
@@ -87,7 +87,53 @@ export default defineConfig({
 
 由于 JSON 文件格式的限制，`package.json` 中只能定义数字、字符串、布尔值、数组等简单类型的值，当我们需要设置函数类型的值时，建议在 Modern.js 配置文件中进行设置。
 
-## 注意事项
+### 注意事项
 
 - 不建议同时使用 `package.json` 和 `modern.config.js` 进行配置。如果同时使用了两者并出现配置冲突，Modern.js 会在命令行进行提示。
 - `@modern-js/runtime` 导出了同名的 [defineConfig](/apis/app/runtime/app/define-config) API，请注意区分。
+
+## 本地调试配置
+
+为了便于本地调试配置，Modern.js 支持在项目根目录下创建 `modern.config.local.(ts|js|mjs)` 文件，用于覆盖 `modern.config.(ts|js|mjs)` 中的配置选项。
+
+### 示例
+
+比如，项目的 `modern.config.ts` 中配置了端口号为 `3000`:
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    port: 3000,
+  },
+});
+```
+
+如果你在本地调试时需要将端口号修改为 `3001`，但是又不希望修改当前项目的 `modern.config.ts` 文件，那么可以创建一个 `modern.config.local.ts` 文件，并添加以下配置：
+
+```ts title="modern.config.local.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    port: 3001,
+  },
+});
+```
+
+`modern.config.local.ts` 文件中的配置会与 `modern.config.ts` 中的配置进行深层合并，并覆盖 `modern.config.ts` 中的配置选项，因此 `server.port` 会被覆盖为 `3001`。
+
+### 注意事项
+
+在使用 `modern.config.local.ts` 时，请注意以下事项：
+
+- `modern.config.local.ts` 文件仅会在执行 `modern dev` 或 `modern start` 命令时被加载，当执行 `modern build` 时不会被加载。
+- `modern.config.local.ts` 文件的优先级不仅高于 `modern.config.ts`，也高于 `package.json` 中的 `modernConfig` 字段。
+- 由于 `modern.config.local.ts` 仅在本地调试时使用，因此不建议将其提交到代码仓库中，请确保项目的 `.gitignore` 文件中包含 `modern.config.local.ts` 等文件。
+
+```bash title=".gitingore"
+modern.config.local.ts
+modern.config.local.js
+modern.config.local.mjs
+```

package/zh/guides/advanced-features/bff/function.mdx

@@ -41,7 +41,7 @@ export default () => {
 };
 ```
 
-:::info 注
+:::info
 Modern.js 生成器已经在 `tsconfig.json` 中配置 `@api` 别名，因此可以直接通过别名的方式引入函数。
 
 :::
@@ -102,7 +102,7 @@ Modern.js 中，BFF 函数对应的路由系统是基于文件系统实现的，
 
 Modern.js 的 BFF 函数需要遵循 RESTful API 标准来定义, 遵循 HTTP Method 规范，并且不允许自由定义参数。
 
-:::info 注
+:::info
 假设函数允许自由定义参数，产出的路由必然由**私有协议**进行调用（原因是无法区分请求参数与请求体），而无法实现任意的 RESTful API。
 
 如果服务仅用于应用本身不存在问题，但它**不标准的接口定义**无法融入更大的体系。 在多个系统共同工作的情况下（例如 BFF 低码搭建），会导致其他系统也需要遵循**私有协议**。
@@ -141,7 +141,7 @@ export const post = async () => {
 
 - 可以在一个文件中定义多个不同 Method 的函数，但如果定义多个相同 Method 的函数，则只有第一个会生效。
 
-:::info 注
+:::info
 需要注意的是，定义的函数都应该是异步的，与函数调用时类型有关，后面会提到。
 
 :::

package/zh/guides/advanced-features/code-split.mdx

@@ -74,7 +74,7 @@ function MyComponent() {
 
 `loadable` 更多用法请见 [loadable API](/apis/app/runtime/utility/loadable)。
 
-:::info 注
+:::info
 `loadable` 开箱即用的支持 SSR，但不支持和 Suspense 一起使用，如果是 CSR 项目可以使用 [loadable.lazy](https://loadable-components.com/docs/suspense/)
 
 :::

package/zh/guides/advanced-features/compatibility.mdx

@@ -31,7 +31,7 @@ Modern.js 在编译时默认通过 [core-js](https://github.com/zloirock/core-js
 
 默认情况下会根据项目 Browserslist 的设置情况引入所需的 Polyfill 代码， 这样基本不用再担心项目源码和第三方依赖的 Polyfill 问题了，但是因为包含了一些没有用到的 Polyfill 代码，所以最终的包大小可能会有所增加。
 
-:::info 注
+:::info
 对于明确第三方依赖不需要 Polyfill 的场景，可以设置 [`output.polyfill`](/configure/app/output/polyfill) 为 `usage`, 这样 Babel 编译时只会根据代码中使用到的语法引入 Polyfill 代码。
 
 :::

package/zh/guides/advanced-features/eslint.mdx

@@ -16,7 +16,7 @@ sidebar_position: 8
 
 多数问题会被 ESLint 规则的自动修复功能或 [Prettier](https://prettier.io/) 的代码格式化功能（已被集成到 ESLint 里）自动解决，开发者不需要关心问题的细节和解决方式。
 
-:::info 注
+:::info
 主要在 IDE 保存文件的环节执行这种自动修复，少数漏网之鱼会在提交代码环节被自动修复。
 
 :::
@@ -45,7 +45,7 @@ pnpm run lint:error
 /* eslint-enable filenames/match-exported */
 ```
 
-:::info 注
+:::info
 在 VS Code 编辑器里输入 eslint，会自动出现关于 "eslint-disable" 的提示框，选择提示选项生成对应注释对。
 
 :::
@@ -76,7 +76,7 @@ pnpm run lint:error
 
 Modern.js 的应用工程、模块工程，源代码目录里都会默认有这个配置文件，是针对 Universal JS 代码设计的。
 
-:::info 注
+:::info
 Universal JS 代码是既能浏览器端也能在服务器端运行的代码。
 
 :::

package/zh/guides/advanced-features/ssr.mdx

@@ -66,7 +66,7 @@ Warning: Expected server HTML to contain a matching <div> in <div>.
 
 这是 React 在客户端执行 hydrate 逻辑时，发现渲染结果与 SSR 渲染结果不一致造成的。虽然页面表现正常，但在复杂应用中，很有可能因此出现 DOM 层级混乱、样式混乱等问题。
 
-:::info 注
+:::info
 关于 hydrate (注水)逻辑请参考[这里](https://reactjs.org/docs/react-dom.html#hydrate)。
 
 :::

package/zh/guides/basic-features/alias.mdx

@@ -13,7 +13,7 @@ Modern.js 允许在 JS 和 CSS 中使用别名导入自定义目录下的模块
 }
 ```
 
-:::info 注
+:::info
 在开启可选功能时，生成器也会动态的添加内置别名，例如启用 BFF 时默认会添加 `@api` 别名。
 
 :::

package/zh/guides/basic-features/builder.mdx

@@ -6,7 +6,7 @@ sidebar_position: 2
 
 **Modern.js 的构建能力由 [Modern.js Builder](https://modernjs.dev/builder) 提供。**
 
-Modern.js Builder 是 Modern.js 体系的核心组件之一，它是一个面向现代 Web 开发场景的构建引擎，可以脱离 Modern.js 被独立使用。Modern.js Builder 同时支持 webpack 和 rspack 等多种打包工具，默认情况下使用最成熟的 webpack 进行打包。
+Modern.js Builder 是 Modern.js 体系的核心组件之一，它是一个面向 Web 开发场景的构建引擎，可以脱离 Modern.js 被独立使用。Modern.js Builder 同时支持 webpack 和 Rspack 等多种打包工具，默认情况下使用最成熟的 webpack 进行打包。
 
 ## 构建架构
 
@@ -14,7 +14,7 @@ Modern.js Builder 是 Modern.js 体系的核心组件之一，它是一个面向
 
 - 上层研发框架：Modern.js。
 - 通用构建引擎：Modern.js Builder。
-- 底层打包工具：webpack 和 rspack。
+- 底层打包工具：webpack 和 Rspack。
 
 <img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/builder-layers-1117.png" style={{ maxWidth: '540px' }} />
 

package/zh/guides/basic-features/css/postcss.mdx

@@ -10,7 +10,7 @@ sidebar_position: 3
 
 1. [Autoprefixer](https://github.com/postcss/autoprefixer) 根据需要支持的浏览器范围，会自动为 CSS 规则添加需要的浏览器厂商前缀。Modern.js 默认支持的浏览器范围为：`['> 0.01%', 'not dead', 'not op_mini all']`。
 
-:::info 注意
+:::info意
   - 【支持的浏览器范围为：`> 0.01%`】是指浏览器市场份额大于 0.01%。
   - `not dead` 是指不包含官方不再支持的浏览器和过去24个月没有更新的浏览器。
   - `not op_mini all` 是指不包含 Opera Mini。

package/zh/guides/basic-features/html.mdx

@@ -217,7 +217,7 @@ Modern.js 也支持 HTML 语法。默认情况下，Modern.js 的应用工程中
 
 在 `config/html/` 目录下，创建 `index.html` 文件,该文件将替代默认的 HTML 模板。
 
-:::info 注
+:::info
 内部默认 HTML 模板可以在 `node_modules/.modern-js/${entryName}/index.html` 中查看。
 
 :::

package/zh/guides/topic-detail/framework-plugin/hook.mdx

@@ -76,7 +76,7 @@ pipeline.run(5); // 6
 
 上面的例子就是以 Pipeline 为例描述的，这里就不赘述了，在 Pipeline 这个大类中，提供了两个小类：Sync 和 Async，顾名思义，它们的区别就是管理的函数的类型是 Sync 的还是 Async 的。
 
-:::info 注
+:::info
 当 Pipeline 中没有函数或者所有函数都调用了 `next` 函数，则就需要在运行的时候提供：
 
 ```ts

package/zh/guides/topic-detail/generator/config/common.mdx

@@ -53,36 +53,36 @@ scenes 配置只能在 `@modern-js/create` 的 `--config` 参数中使用，不
 
 ### noNeedInstall
 
-- Type: `boolean`
-- Default: `false`
+- **类型：** `boolean`
+- **默认值：** `false`
 
 是否跳过依赖安装。
 
 ### noNeedGit
 
-- Type: `boolean`
-- Default: `false`
+- **类型：** `boolean`
+- **默认值：** `false`
 
 是否跳过 git 初始化和提交初始 commit。
 
 ### successInfo
 
-- Type: `string`
-- Default: 不同工程方案的命令操作提示
+- **类型：** `string`
+- **默认值：** 不同工程方案的命令操作提示
 
 自定义创建项目成功的提示信息。
 
 ### isMonorepoSubProject
 
-- Type: `boolean`
-- Default: `false`
+- **类型：** `boolean`
+- **默认值：** `false`
 
 是否为 Monorepo 子项目。
 
 ### isTest
 
-- Type: `boolean`
-- Default: `false`
+- **类型：** `boolean`
+- **默认值：** `false`
 
 作用于应用项目，标识是否为测试项目。
 
@@ -91,8 +91,8 @@ scenes 配置只能在 `@modern-js/create` 的 `--config` 参数中使用，不
 
 ### isPublic
 
-- Type: `boolean`
-- Default: `false`
+- **类型：** `boolean`
+- **默认值：** `false`
 
 作用于模块 (Module) 项目，标识是否需要对外发布。
 

package/zh/guides/topic-detail/generator/plugin/api/input/addInputBefore.mdx

@@ -45,7 +45,7 @@ context.addInputBefore('packageManager', {
 });
 ```
 
-:::info 注意事项
+:::info意事项
 
 1. 添加问题的 key 不能和 Modern.js 提供的项目类型自身的问题的 key 重复
 

package/zh/guides/topic-detail/micro-frontend/c05-mixed-stack.mdx

@@ -16,7 +16,7 @@ Modern.js 微前端方案是基于 [Garfish](https://garfishjs.org/) 封装的
 **Modern.js** 子应用编译后会生成标准的 [Garfish 子应用导出](https://www.garfishjs.org/guide/start#2%E5%AF%BC%E5%87%BA-provider-%E5%87%BD%E6%95%B0)。
 所以可以直接接入标准的微前端主应用。
 
-:::info 注
+:::info
 子应用是 **Modern.js**，主应用使用的原生 Garfish 微前端时，**子应用调试模式** 不可用。
 
 :::

package/zh/guides/topic-detail/model/auto-actions.mdx

@@ -80,7 +80,7 @@ function Counter() {
 
 根据 `a`、`b`、`c` 三个不同的字段分别生成 `setA`、`setB`、`setC` 三个 Actions。
 
-:::info 注
+:::info
 当用户自定义的 Action 和 Modern.js 自动生成的 Action 名字一致时，用户自定义的 Action 优先级更高。例如，
 在 `countModel` 中已经自定义 `setA` 这个 Action，调用 `actions.setA()` 时，最终执行的是用户自定义的 `setA`。
 

package/zh/guides/topic-detail/model/define-model.mdx

@@ -23,7 +23,7 @@ const fooModel = model('foo').define({
 });
 ```
 
-:::info 注
+:::info
 - Model 中的 Action 中不能包含有副作用的逻辑，如请求 HTTP 接口，访问 localStorage 等。
 - `setValue` 内部直接修改了入参 State，看起来是违反了纯函数的定义，实际上 Reduck 内部使用 [immer](https://github.com/immerjs/immer) 来修改不可变对象，保证了这种写法不会影响对象的不可变性，所以 `setValue` 仍然是一个纯函数。当然，你也可以直接在 Action 中返回一个新对象，不过这样的写法会更加复杂一些。
 

package/zh/guides/topic-detail/model/manage-effects.mdx

@@ -187,7 +187,7 @@ const todoModel = model('todo').define((context, utils) => ({
 }));
 ```
 
-:::info 注
+:::info
 可以使用 `use` 函数加载其它 Model（包括 Model 自身），实现 [Model 间通信](/guides/topic-detail/model/model-communicate)。
 
 :::

package/zh/guides/topic-detail/model/quick-start.mdx

@@ -16,7 +16,7 @@ Reduck 在 MVC 模式中，扮演 M(Model) 的角色，React UI Component 对应
 
 Modern.js 的状态管理解决方案，是通过内置 Reduck 实现的。在 Modern.js 中使用 Reduck，不仅免去了手动集成的环节，而且所有 Reduck API 都可以从 Modern.js 的 Runtime 包中直接导入使用，具有更好的一致性体验。
 
-:::info 注
+:::info
 1. Modern.js 中使用 Reduck API，需要先设置 [runtime.state](/configure/app/runtime/state) 以启用状态管理插件。
 2. Reduck 也可以脱离 Modern.js 作为状态管理库[单独使用](/guides/topic-detail/model/use-out-of-modernjs)。
 
@@ -101,7 +101,7 @@ function Counter() {
 
 `useModel` 获取 `countModel` 的 `state` 和 `actions`，组件展示当前计算器的值，点击 `add` 按钮，计数器自增 1。
 
-:::info 注
+:::info
 由于使用的案例比较简单，这里并没有严格按照 MVC 模式进行分层，组件 `Counter` 同时起到了 V 和 C 两层的作用。
 
 :::

package/zh/guides/topic-detail/model/test-model.mdx

@@ -35,7 +35,7 @@ describe('test model', () => {
 });
 ```
 
-:::info 注
+:::info
 这里使用的 [`createStore`](/apis/app/runtime/model/create-store) 是从 `@modern-js/runtime/testing` 导入的，内部会使用 [`runtime.state`](/configure/app/runtime/state) 的配置去创建 `store`。
 
 :::

package/zh/guides/topic-detail/model/use-model.mdx

@@ -111,7 +111,7 @@ const [state, actions] = useModel(
 
 通过 `useStaticModel` 获取 Model ，将 Model 中的状态作为静态状态使用。可以保证组件每次访问到的 Model 的 State 都是最新值，但是 Model 的 State 的变化，并不会引起当前组件的重新渲染。
 
-:::info 注
+:::info
 `useStaticModel` 的使用方式和 `useModel` 完全一致。
 
 :::
@@ -169,7 +169,7 @@ function ThreeComponent() {
 
 通过 `useLocalModel` 获取 Model ，将 Model 中的状态作为局部状态使用。此时 Model State 的变化，只会引起当前组件的重新渲染，但是不会引起其他使用了该 Model 的组件重新渲染。效果和通过 React 的 `useState` 管理状态类似，但是可以将状态的管理逻辑从组件中解耦，统一收敛到 Model 层。
 
-:::info 注
+:::info
 `useLocalModel` 的使用方式和 `useModel` 完全一致。
 
 :::
@@ -241,7 +241,7 @@ setInterval(() => {
 
 完整的示例代码可以在[这里](https://github.com/modern-js-dev/modern-js-examples/tree/main/series/tutorials/runtime-api/model/counter-model-outof-react)查看。
 
-:::info 注
+:::info
 如果是通过 [`createStore`](/apis/app/runtime/model/create-store) 手动创建的 Store 对象，无需通过 `useStore` 在组件内获取，即可直接使用。
 
 :::

package/zh/guides/topic-detail/monorepo/create-sub-project.mdx

@@ -34,12 +34,12 @@ pnpm run new
   模块（内部）
 ```
 
-:::info 注
+:::info
 「应用」与「应用（测试）」都是「应用」类型的项目，区别是「应用」类型的子项目会创建在 `./apps` 目录下，而 「应用（测试）」类型的子项目会创建在 `./examples` 目录下。
 
 :::
 
-:::info 注
+:::info
 「模块」与「模块（内部）」都是「模块」类型的项目，区别之一是「模块」类型的子项目会创建在 `./packages` 目录下，而「模块（内部）」类型的子项目会创建在 `./features` 目录下。
 
 对于「模块」类型的子项目允许被发布到外部（例如 npm)，而对于「模块（内部）」的子项目则可以在应用项目中直接使用其源码（该特性是「模块」项目不具备的，应用项目对于「模块（内部）」子项目做了特殊处理），因此这类子项目不需要发布到外部。

package/zh/guides/topic-detail/monorepo/sub-project-interface.mdx

@@ -109,7 +109,7 @@ export default App;
 
 到此为止我们创建了一个可以被发布到外部的组件项目、一个转换字符串的内部模块项目以及一个使用组件和内部模块的应用项目，如果直接运行应用项目还暂时无法正常使用。接下来将要介绍如何让它们能够互相联调使用，成功的使应用子项目 `apps/app` 正常运行。
 
-:::info 注
+:::info
 启动 `apps/app` 项目之前需要先构建（`pnpm run build`） `packages/component`。
 
 :::
@@ -130,7 +130,7 @@ pnpm add components
 pnpm add internal-lib -D
 ```
 
-:::info 注
+:::info
 注意这里将 internal-lib 作为 `apps/app` 项目的开发依赖，因为在构建环境会被打包到构建产物中。
 
 :::

package/zh/tutorials/first-app/c02-component.mdx

@@ -48,7 +48,7 @@ function App() {
 
 可以看到 Ant Design 导出的组件，已经具备了完整的样式。
 
-:::info 注
+:::info
 Modern.js 会[自动按需导入 Ant Design 组件需要的 CSS](https://github.com/ant-design/babel-plugin-import)。
 
 :::

package/zh/tutorials/first-app/c03-css.mdx

@@ -94,7 +94,7 @@ export default Avatar;
 
 执行 `pnpm run dev`，运行结果应该是一样的。
 
-:::info 注
+:::info
 采用目录形式 `Avatar/index.tsx` 而不是单文件形式 `Avatar.tsx` 的原因是，之后可以方便的在目录内部增加子文件，包括专用的资源（图片等）、专用子组件、CSS 文件等。
 
 :::
@@ -293,7 +293,7 @@ import '../styles/utils.css';
 }
 ```
 
-:::info 注
+:::info
 Modern.js 集成了 [PostCSS](/guides/basic-features/css/postcss)，支持现代 CSS 语法特性，比如 [custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)。
 
 :::
@@ -314,7 +314,7 @@ Modern.js 集成了 [PostCSS](/guides/basic-features/css/postcss)，支持现代
 
 ![design2](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/06/result3.png)
 
-:::info 注
+:::info
 此处只是为了演示 Utility Class 用法。真实项目中，在有 Tailwind CSS 的情况下，这种 Utility Class 没什么价值，应该通过配置 Design System 的 [**theme**](https://tailwindcss.com/docs/customizing-colors) 来增加字体颜色。
 
 `utils.css` 也可以写成 `utils.scss` 或 `utils.less`，Modern.js 对 SCSS 和 Less 同样提供开箱即用的支持。

package/zh/tutorials/first-app/c04-routes.mdx

@@ -84,7 +84,7 @@ function Index() {
 }
 ```
 
-:::info 注
+:::info
 Modern.js 默认集成了 react-helmet，也可以结合 SSR 使用，满足 SEO 需求。
 
 :::

package/zh/tutorials/first-app/c06-model.mdx

@@ -10,7 +10,7 @@ title: 添加业务模型（状态管理）
 
 因此会开始编写一些跟 UI 完全无关的业务逻辑，如果继续写在组件代码中，会产生越来越多的面条式代码。为此，我们引入了一种叫做 **业务模型（Model）** 的代码模块，将这些业务逻辑和 UI 解耦。
 
-:::info 注意
+:::info意
 使用状态管理相关 API，需要先启用配置项 [runtime.state](/docs/configure/app/runtime/state)：
 
 ```ts title="modern.config.ts"