@modern-js/main-doc 2.11.0 → 2.13.0

package/docs/en/guides/get-started/upgrade.mdx

@@ -25,24 +25,24 @@ You can see that the dependency in the project `package.json` has been changed t
 
 ## Specify version upgrade
 
-Modern.js all packages are published using the **unified version number**.
+All packages of Modern.js are published using the **unified version number**.
 
-According to the website Release Note, developers can also manually upgrade the project to the desired version.
+According to the website release note, developers can also manually upgrade the project to the desired version.
 
 :::tip
 When upgrading, you need to upgrade to all packages provided by the Modern.js, rather than upgrading a single dependency.
 
 :::
 
-## lock child dependency
+## Lock nested dependency
 
-When there is a problem with one of the child dependencies of the project, and the Modern.js cannot be updated immediately, you can use the package manager to lock the child dependency version.
+When there is a problem with one of the nested dependencies of the project, and the Modern.js cannot be updated immediately, you can use the package manager to lock the child dependency version.
 
 ### pnpm
 
 For projects using pnpm, add the following configuration to the `package.json` in the **project root directory** and re-execute `pnpm install`:
 
-```json
+```json title="package.json"
 {
   "pnpm": {
     "overrides": {
@@ -56,7 +56,7 @@ For projects using pnpm, add the following configuration to the `package.json` i
 
 For projects using Yarn, add the following configuration to the `package.json` in the **project root directory** and re-execute `yarn install`:
 
-```json
+```json title="package.json"
 {
   "resolutions": {
     "package-name": "^1.0.0"
@@ -68,7 +68,7 @@ For projects using Yarn, add the following configuration to the `package.json` i
 
 For projects using Npm, add the following configuration to the `package.json` in the **project root directory** and re-execute `npm install`:
 
-```json
+```json title="package.json"
 {
   "overrides": {
     "package-name": "^1.0.0"

package/docs/en/guides/topic-detail/framework-plugin/hook.mdx

@@ -32,7 +32,7 @@ pipeline.run(1); // 4
 pipeline.run(5); // 12
 ```
 
-In this example, a `Pipeline<number, number>` is created on line 3. This means that when you run it, you need to pass in a `number`, and you will get a `number` as a result，the type is:
+In this example, a `Pipeline<number, number>` is created on line 3. This means that when you run it, you need to pass in a `number`, and you will get a `number` as a result, the type is:
 
 ```ts
 (count: number, next: (nextCount: number) => number) => number;

package/docs/en/guides/topic-detail/generator/codesmith/api/json.mdx

@@ -35,7 +35,7 @@ Get the JSON file content.
 
 Parameter:
 
-- resource: `FsResource`. A file resource，get by `context.materials.default.get(<filename>)`.
+- resource: `FsResource`. A file resource, get by `context.materials.default.get(<filename>)`.
 
 ### extend
 
@@ -43,7 +43,7 @@ Merge objects into a JSON file.
 
 Parameter:
 
-- resource: `FsResource`. A file resource，get by `context.materials.default.get(<filename>)`.
+- resource: `FsResource`. A file resource, get by `context.materials.default.get(<filename>)`.
 - obj: `Record<string, any>`. Object to be merged.
 
 ### update
@@ -52,5 +52,5 @@ pdate object fields to JSON file.
 
 Parameter:
 
-- resource: `FsResource`. A file resource，get by `context.materials.default.get(<filename>)`.
+- resource: `FsResource`. A file resource, get by `context.materials.default.get(<filename>)`.
 - operation: `{ query: Record<string, any>; update: Record<string, any> }`. Update operation, use gesture to view [declaration-update](https://www.npmjs.com/package/declaration-update) in detail.

package/docs/en/guides/topic-detail/generator/config/app.mdx

@@ -75,7 +75,7 @@ BFF type (bffType), supports two options:
 
 ##### framework
 
-BFF runtime framework (framework)，supports two options:
+BFF runtime framework (framework), supports two options:
 
 - Express(express)
 

package/docs/en/guides/topic-detail/generator/config/monorepo.mdx

@@ -12,7 +12,7 @@ The Monorepo project supports the creation of sub-projects by using the new comm
 
 ### solution
 
-Subproject type(solution)，the different subproject type fields are:
+Subproject type(solution), the different subproject type fields are:
 
 - Application (mwa)
 - Application (Test) (mwa_test)

package/docs/en/guides/topic-detail/generator/plugin/api/file/addHelper.mdx

@@ -4,7 +4,7 @@ sidebar_position: 2
 
 # addHelper
 
-For text files, add a customized Help function of Handlebars，the specific viewable document[Custom Helpers](https://handlebarsjs.com/guide/#custom-helpers).
+For text files, add a customized Help function of Handlebars, the specific viewable document[Custom Helpers](https://handlebarsjs.com/guide/#custom-helpers).
 
 This method is available on the `onForged` time to live API parameter.
 

package/docs/en/guides/topic-detail/model/manage-effects.mdx

@@ -2,6 +2,7 @@
 sidebar_position: 5
 title: Management Effect
 ---
+
 # Management Effect
 
 The actions in the model must be pure functions and cannot have any side effects during execution. However, in real-world scenarios, we often encounter many side effects, such as: requesting data from an HTTP API to obtain state data, or modifying `localStorage` or sending events while updating the state. In Reduck, side effects are managed through the model's `effects` function.
@@ -88,7 +89,7 @@ For this type of side effect scenario, `handleEffect` stipulates that the state
 {
   result: null,
   error: null,
-  pending: false，
+  pending: false,
 }
 ```
 

package/docs/en/guides/topic-detail/model/model-communicate.mdx

@@ -188,7 +188,7 @@ const fooModel = model('foo').define((context, { use, onMount }) => {
   let actions;
 
   onMount(() => {
-    // after fooModel mounted，get actions
+    // after fooModel mounted, get actions
     [, actions] = use(fooModel);
   });
 

package/docs/en/guides/topic-detail/model/use-model.mdx

@@ -2,6 +2,7 @@
 sidebar_position: 3
 title: Use Models
 ---
+
 # Use Models
 
 ## Using Models in Components
@@ -146,7 +147,7 @@ will always get the initial value of Input.
 
 :::
 
-`useStaticModel` is also suitable for use with animation libraries such as [react-three-fiber](https://github.com/pmndrs/react-three-fiber), because binding fast-changing states in animation component UI can easily cause [performance issues](https:/docs.pmnd.rs/react-three-fiber/advanced/pitfalls#never-bind-fast-state-reactive). In this case, you can choose to use `useStaticModel`, which only subscribes to the State but does not cause the view component to re-render. Here is a simplified example:
+`useStaticModel` is also suitable for use with animation libraries such as [react-three-fiber](https://github.com/pmndrs/react-three-fiber), because binding fast-changing states in animation component UI can easily cause [performance issues](https://docs.pmnd.rs/react-three-fiber/advanced/pitfalls#never-bind-fast-state-reactive). In this case, you can choose to use `useStaticModel`, which only subscribes to the State but does not cause the view component to re-render. Here is a simplified example:
 
 ```ts
 function ThreeComponent() {

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

@@ -0,0 +1,31 @@
+---
+sidebar_position: 3
+---
+
+# Build FAQ
+
+If you encounter build-related problems, you can refer to the following documents:
+
+## General FAQ
+
+Please refer to [Modern.js Builder - General FAQ](https://modernjs.dev/builder/en/guide/faq/general.html), which contains some general questions about concepts, such as:
+
+- The relationship between Modern.js Builder and Modern.js?
+- Can Builder be used to build libraries or UI components?
+- Will Builder support Vite?
+
+## Features FAQ
+
+Please refer to [Modern.js Builder - Features FAQ](https://modernjs.dev/builder/en/guide/faq/features.html), which contains an introduction to some common building features, such as:
+
+- How to import UI Component library on demand?
+- How to run ESLint during compilation?
+- How to configure CDN path for static assets?
+
+## Exceptions FAQ
+
+Please refer to [Modern.js Builder - Exceptions FAQ](https://modernjs.dev/builder/en/guide/faq/exceptions.html), which contains some common construction problems, such as:
+
+- 'compilation' argument error when webpack compiling?
+- Compile error `You may need additional loader`?
+- Find `exports is not defined` runtime error?

package/docs/en/tutorials/foundations/introduction.mdx

@@ -26,5 +26,3 @@ We have prepared a tutorial on creating a "contact list app" that you can follow
 - Container components
 - New portal
 - ...
-
-Translated with www.DeepL.com/Translator (free version)

package/docs/zh/apis/app/hooks/config/icon.mdx

@@ -1,18 +1,56 @@
 ---
-title: icon.png
+title: icon
 sidebar_position: 2
 ---
-# icon.png
 
-应用工程方案 App Icon 文件。
+# Icon
 
-项目根目录下 `config/icon.png` 时，可以在构建时向 html 页面注入 app icon 信息：
+## 设置 favicon
+
+当项目根目录的 `config` 目录下存在 `favicon.*` 文件时，Modern.js 会自动将该文件设置到 [html.favicon](/configure/app/html/favicon) 配置项中，用于生成页面的 favicon 图标：
+
+```
+./config
+└── favicon.ico
+```
+
+构建完成后，可以看到 HTML 中自动生成了以下标签：
+
+```html
+<link rel="icon" href="/favicon.ico" />
+```
+
+### 查找顺序
+
+在设置 app icon 时，Modern.js 会按以下顺序寻找文件：
+
+- favicon.png
+- favicon.jpg
+- favicon.jpeg
+- favicon.svg
+- favicon.ico
+
+## 设置 app icon
+
+当项目根目录的 `config` 目录下存在 `icon.*` 文件时，Modern.js 会自动将该文件设置到 [html.appIcon](/configure/app/html/app-icon) 配置项中，用于生成 iOS 系统下的 apple-touch-icon 图标。
 
 ```
 ./config
 └── icon.png
 ```
 
-最终 html 中会注入 app icon `link` 标签, 如下:
+构建完成后，可以看到 HTML 中自动生成了以下标签：
+
+```html
+<link rel="apple-touch-icon" sizes="180*180" href="/static/image/icon.png" />
+```
+
+### 查找顺序
+
+在设置 app icon 时，Modern.js 会按以下顺序寻找文件：
 
-![app-icon](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/api/app-icon.png)
+- icon.png
+- icon.jpg
+- icon.jpeg
+- icon.svg
+- icon.ico

package/docs/zh/apis/app/hooks/src/pages.mdx

@@ -85,7 +85,7 @@ pages 目录下的文件满足以下条件的不会被当做路由文件
 import React from 'react';
 import UserLayout from 'xxxx';
 
-export default const App = ({Component, ...pageProps}:{ Component: React.ComponentType}) => {
+export const App = ({Component, ...pageProps}:{ Component: React.ComponentType}) => {
   return (
     <UserLayout>
       <Component {...pageProps} />

package/docs/zh/apis/app/runtime/core/use-loader.mdx

@@ -5,6 +5,10 @@ title: useLoader
 
 一个同构的 API，通常会用来做异步请求。当 SSR 的时候，服务端使用 `useLoader` 预加载数据，同时浏览器端也会复用这部分数据。
 
+:::tip
+在使用 Rspack 作为打包工具时，暂不支持使用 useLoader API。
+:::
+
 ## 使用姿势
 
 ```ts

package/docs/zh/apis/app/runtime/model/handle-effect.mdx

@@ -2,9 +2,10 @@
 sidebar_position: 7
 title: handleEffect
 ---
+
 # handleEffect
 
-import ReduckTip from "@site-docs/components/reduck-tip"
+import ReduckTip from '@site-docs/components/reduck-tip';
 
 <ReduckTip />
 

package/docs/zh/apis/app/runtime/model/model_.mdx

@@ -2,9 +2,10 @@
 sidebar_position: 1
 title: model
 ---
+
 # model
 
-import ReduckTip from "@site-docs/components/reduck-tip"
+import ReduckTip from '@site-docs/components/reduck-tip';
 
 <ReduckTip />
 
@@ -61,7 +62,8 @@ const fooModel = model('foo').define({
 - context: Context，Reduck 上下文对象，可以获取底层的 `store` 对象。`store` 除支持 Redux Store 的所有 [API](https://redux.js.org/api/store) 以外，还挂载了用于消费 Model 的 `use` 的方法，和用于卸载 Model 的 `unmount` 方法。
 - utils: Utils，定义 Model 时，常用的工具函数：`use`、`onMount`。`use` 作用同 `store` 对象上的 `use`，`onMount` 是 Model 挂载后的钩子函数。
 
-{/* TODO: @anchao 调整类型  */}
+{/* TODO: @anchao 调整类型 */}
+
 ```ts
 interface Utils {
   use: UseModel;

package/docs/zh/blog/updates/2022-0708-updates.md

@@ -39,8 +39,7 @@ npx @modern-js/upgrade
 
 新的模块工程项目，不仅支持对产物做 bundless 构建，也支持 bundle 构建。通过配置 `buildConfig` 下的 [`buildType`](https://modernjs.dev/v1/docs/apis/module/config/output/build-config/build-type) ，即可进行 bundle 构建：
 
-```ts
-// modern.config.ts
+```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/module-tools';
 
 export default defineConfig({

package/docs/zh/components/enable-bff.mdx

@@ -6,7 +6,7 @@ import { Tabs, Tab as TabItem } from "@theme";
 <Tabs>
   <TabItem value="express" label="Express.js" default>
 
-```ts title="edenx.config.ts"
+```ts title="modern.config.ts"
 import expressPlugin from '@modern-js/plugin-express';
 import bffPlugin from '@modern-js/plugin-bff';
 
@@ -18,7 +18,7 @@ export default defineConfig({
   </TabItem>
   <TabItem value="koa" label="Koa.js">
 
-```ts title="edenx.config.ts"
+```ts title="modern.config.ts"
 import koaPlugin from '@modern-js/plugin-koa';
 import bffPlugin from '@modern-js/plugin-bff';
 

package/docs/zh/configure/app/html/script-loading.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_label: scriptLoading
+---
+
+# html.scriptLoading
+
+:::tip
+该配置由 Modern.js Builder 提供，更多信息可参考 [html.scriptLoading](https://modernjs.dev/builder/api/config-html.html#htmlscriptloading)。
+:::
+
+import Main from '@modern-js/builder-doc/docs/zh/config/html/scriptLoading.md';
+
+<Main />

package/docs/zh/configure/app/runtime/router.mdx

@@ -18,7 +18,7 @@ import RouterLegacyTip from "@site-docs/components/router-legacy-tip"
 ## basename
 
 - **类型：** `string`
-- **默认值：** ``
+- **默认值：** `/`
 
 设置客户端路由的 `basename`，通常用于应用需要部署在域名非根路径下的场景。
 

package/docs/zh/configure/app/source/disable-entry-dirs.mdx

@@ -7,14 +7,14 @@ sidebar_label: disableEntryDirs
 - **类型：** `string[]`
 - **默认值：** `[]`
 
-默认会根据 `src` 目录识别应用入口，可通过该选项禁止某些目录被识别为应用入口。
+Modern.js 默认会根据 `src` 目录识别应用入口，你可以通过该选项禁止某些目录被识别为应用入口。
 
 例如，当配置与目录结构如下时：
 
 ```ts title="modern.config.ts"
 export default defineConfig({
   source: {
-    disableEntryDirs: './src/one',
+    disableEntryDirs: ['./src/one'],
   },
 });
 ```

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

@@ -0,0 +1,13 @@
+---
+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/configure/app/tools/swc.mdx

@@ -19,13 +19,14 @@ Modern.js 提供了开箱即用的 SWC 插件，可以为你的 Web 应用提供
 
 ## 安装
 
-使用前需要安装 `@modern-js/plugin-swc` 插件。
+首先，你需要执行 `pnpm run new` 启用 SWC 编译：
 
 ```bash
-pnpm add @modern-js/plugin-swc -D
+? 请选择你想要的操作：启用可选功能
+? 启用可选功能：启用「SWC 编译」
 ```
 
-安装完成后，只需在 `modern.config.ts` 文件中注册 SWC 插件，即可启用 SWC 编译和压缩能力。
+执行完成后，你只需在 `modern.config.ts` 文件中注册 SWC 插件，即可启用 SWC 编译和压缩能力。
 
 ```ts title="modern.config.ts"
 import appTools, { defineConfig } from '@modern-js/app-tools';

package/docs/zh/configure/app/usage.mdx

@@ -19,17 +19,33 @@ Modern.js 不支持同时在 package.json 中和 modern.config.ts 中配置同
 
 ## 在配置文件中配置
 
-Modern.js 的配置文件定义在项目的根目录下，支持 `.js`, `.ts` 和 `.mjs` 格式：
+Modern.js 的配置文件定义在项目的根目录下，支持 `.ts`, `.js` 和 `.mjs` 格式：
 
-- `modern.config.js`
 - `modern.config.ts`
+- `modern.config.js`
 - `modern.config.mjs`
 
-### modern.config.js
+### modern.config.ts（推荐）
+
+我们推荐使用 .ts 格式的配置文件，它提供了友好的 TypeScript 类型提示，从而帮助你避免配置中的错误。
+
+从 `@modern-js/app-tools` 中导入 `defineConfig` 工具函数, 它会帮助你进行配置的类型推导和类型补全：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  source: {
+    alias: {
+      '@common': './src/common',
+    },
+  },
+});
+```
 
-`modern.config.js` 中可以使用 JavaScript 语法，因此比 `package.json` 更加灵活。
+### modern.config.js
 
-比如，你可以在 `modern.config.js` 中定义函数类型的配置选项：
+如果你在开发一个非 TypeScript 项目，可以使用 .js 格式的配置文件：
 
 ```js title="modern.config.js"
 export default {
@@ -51,24 +67,6 @@ export default {
 };
 ```
 
-### modern.config.ts（推荐）
-
-我们推荐使用 .ts 格式的配置文件，它提供了友好的 TypeScript 类型提示，从而帮助你避免配置中的错误。
-
-从 `@modern-js/app-tools` 中导入 `defineConfig` 工具函数, 它会帮助你进行配置的类型推导和类型补全：
-
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  source: {
-    alias: {
-      '@common': './src/common',
-    },
-  },
-});
-```
-
 ### 导出配置函数
 
 Modern.js 支持在配置文件中导出一个函数，你可以在函数中动态计算配置，并返回给 Modern.js。
@@ -134,7 +132,7 @@ $ modern build -c modern.prod.config.js
 
 ## 在 package.json 中配置（不推荐）
 
-除了配置文件外，也可以在 `package.json` 中的 `modernConfig` 字段下设置配置选项，如：
+除了配置文件外，你也可以在 `package.json` 中的 `modernConfig` 字段下设置配置项，如：
 
 ```json title="package.json"
 {
@@ -200,3 +198,47 @@ modern.config.local.ts
 modern.config.local.js
 modern.config.local.mjs
 ```
+
+## 合并多份配置
+
+在某些情况下，你可能需要将多份配置合并为一份配置，此时你可以使用 `mergeConfig` 工具函数来合并多个配置。
+
+`mergeConfig` 函数接受一个数组作为参数，数组中的每一项都是一个配置对象，`mergeConfig` 会将数组中的每一项配置对象进行深层合并，自动将多个函数项合并为数组，最终返回一个合并后的配置对象。
+
+### 示例
+
+```ts title="modern.config.ts"
+import { mergeConfig } from '@modern-js/app-tools';
+
+const config1 = {
+  dev: {
+    port: 3000,
+  },
+  tools: {
+    postcss: () => console.log('config1');
+  },
+};
+const config2 = {
+  dev: {
+    port: 3001,
+  },
+  tools: {
+    postcss: () => console.log('config2');
+  },
+};
+
+const mergedConfig = mergeConfig([config1, config2]);
+```
+
+在以上示例中，合并后的配置对象为：
+
+```ts
+const mergedConfig = {
+  dev: {
+    port: 3001,
+  },
+  tools: {
+    postcss: [() => console.log('config1'), () => console.log('config2')],
+  },
+};
+```