@modern-js/main-doc 2.0.0-beta.6 → 2.0.0-beta.7

package/zh/guides/basic-features/proxy.md

@@ -27,7 +27,7 @@ export default defineConfig({
 请求 `http://localhost:8080/go/api` 时，会从 [http://www.example.com/](http://www.example.com/) 返回响应内容。
 
 :::info 补充信息
-配置格式可参考:【[http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware)】。
+配置格式可参考：[http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware)。
 :::
 
 ## 全局代理
@@ -38,7 +38,7 @@ import GlobalProxy from '@site-docs/components/global-proxy.md'
 
 ## BFF 代理
 
-通过配置 [`bff.proxy`](/docs/configure/app/bff/proxy) 可以代理 BFF API 请求到指定的服务上，和[开发环境代理](/docs/configure/app/dev/proxy)不同的是，它同样可以用在生产环境：
+通过配置 [`bff.proxy`](/docs/configure/app/bff/proxy) 可以代理 BFF API 请求到指定的服务上，上述两种代理不同，它同样可以用在生产环境：
 
 ```typescript title="modern.config.ts"
 export default defineConfig({

package/zh/guides/basic-features/routes.md

@@ -13,7 +13,7 @@ Modern.js 内置了对 [React Router 6](https://reactrouter.com/en/main) 的**
 
 以 `routes/` 为约定的入口，Modern.js 会自动基于文件系统，生成对应的路由结构。
 
-Modern.js 支持了业界流行的约定路由模式：**嵌套路由**，使用嵌套路由时，页面的路由 与 UI 结构是相呼应的，我们将会详细介绍这种路由模式。
+Modern.js 支持了业界流行的约定式路由模式：**嵌套路由**，使用嵌套路由时，页面的路由 与 UI 结构是相呼应的，我们将会详细介绍这种路由模式。
 
 ```
 /user/johnny/profile                  /user/johnny/posts
@@ -26,11 +26,30 @@ Modern.js 支持了业界流行的约定路由模式：**嵌套路由**，使用
 +------------------+                  +-----------------+
 ```
 
+
 ### 路由文件约定
 
-`routes/` 目录下有两个文件约定 `layout.[jt]sx` 和 `page.[jt]sx`（后面简写为 `.tsx`）。这两个文件决定了应用的布局层次，其中 `layout.tsx` 中作为布局组件，`page.tsx` 作为内容组件，是整个路由表的叶子节点。
+在`routes/` 目录下，目录名会作为路由 url 的映射，Modern.js 有两个文件约定 `layout.[jt]sx` 和 `page.[jt]sx`（后面简写为 `.tsx`）。这两个文件决定了应用的布局层次，其中 `layout.tsx` 中作为布局组件，`page.tsx` 作为内容组件，是整条路由的叶子节点（一条路由有且仅有一个叶子节点，且必须以叶子节点结尾）。
 
-例如，这里 `routes/layout.tsx` 会作为 `/` 路由下所有组件的布局组件使用：
+例如以下目录结构：
+
+```bash
+.
+└── routes
+    ├── page.tsx
+    └── user
+        └── page.tsx
+```
+
+会产出下面两条路由：
+- `/`
+- `/user`
+
+当添加 `layout.tsx` 后， 假设有以下目录
+
+:::info
+这里 `routes/layout.tsx` 会作为 `/` 路由下所有组件的布局组件使用， `routes/user/layout.tsx` 会作为 `/user` 路由下所有路由组件的布局组件使用。
+:::
 
 ```bash
 .
@@ -64,6 +83,18 @@ Modern.js 支持了业界流行的约定路由模式：**嵌套路由**，使用
 
 `<Layout>` 组件是指 `routes/` 目录下所有 `layout.tsx` 文件，它们表示对应路由片段的布局，使用 `<Outlet>` 表示子组件。
 
+```tsx title=routes/layout.tsx
+import { Link, Outlet, useLoaderData } from '@modern-js/runtime/router';
+
+export default () => {
+  return (
+    <>
+      <Outlet></Outlet>
+    </>
+  )
+}
+```
+
 :::note
 `<Outlet>` 是 React Router 6 中新的 API，详情可以查看 [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
 :::
@@ -130,6 +161,8 @@ Modern.js 支持了业界流行的约定路由模式：**嵌套路由**，使用
 
 在组件中，可以通过 [useParams](/docs/apis/app/runtime/router/#useparams) 获取对应命名的参数。
 
+在 loader 中，params 会作为 [loader](/docs/guides/basic-features/data-fetch#loader-函数) 的入参，通过 `params.xxx` 可以获取。
+
 ### 无路径布局
 
 当目录名以 __ 开头时，对应的目录名不会转换为实际的路由路径，例如以下文件目录：
@@ -217,6 +250,7 @@ Modern.js 会生成 `/login` 和 `/sign` 两条路由，`__auth/layout.tsx` 组
 ```
 :::info
 当目录的 layout 组件不存在时，该目录下的 loading 组件也不会生效。
+Modern.js 建议必须有根 layout 和根 loading。
 :::
 
 当路由从 `/` 跳转到 `/blog` 时，如果 `blog/page` 组件的 JS Chunk 还未加载，则会先展示 `loading.tsx` 中导出的组件 UI。
@@ -272,9 +306,6 @@ export default () => {
 
 :::note
 在自控式路由下，开发者如果希望在 SSR 中使用 React Router 6 中 [Loader API](https://reactrouter.com/en/main/hooks/use-loader-data#useloaderdata) 的能力会相对复杂，推荐直接使用约定式路由。Modern.js 已经为你封装好了一切。
-
-<!-- Todo 嵌套路由带来的优化可以补充下文档-->
-如果项目只想升级到 React Router 6，而不希望使用嵌套路由带来的优化，那 [useLoader](/docs/apis/app/runtime/core/use-loader) 在 SSR 下仍然可以工作。
 :::
 
 ## 其他路由方案

package/zh/guides/get-started/quick-start.md

@@ -120,8 +120,7 @@ Starting the modern server...
 info    App running at:
 
   > Local:    http://localhost:8080/
-  > Network:  http://10.94.58.87:8080/
-  > Network:  http://10.254.68.105:8080/
+  > Network:  http://192.168.0.1:8080/
 ```
 
 在浏览器中打开 `http://localhost:8000/`，内容应该和 `pnpm run dev` 时一致。

package/zh/guides/topic-detail/framework-plugin/implement.md

@@ -30,11 +30,23 @@ const MyPlugin = {
 };
 ```
 
-另外，在插件中，允许配置与其他插件的执行顺序，详情可以参考[插件关系](/docs/guides/topic-detail/framework-plugin/relationship)。
+另外，在插件中，允许配置与其他插件的执行顺序。详情可以参考[插件关系](/docs/guides/topic-detail/framework-plugin/relationship)。
 
 ### 插件类型
 
-使用 TypeScript 时，可以引入内置的 `CliPlugin` 类型，为插件提供正确的类型推导：
+Modern-js 支持多种工程开发，如应用工程(app-tools), 模块工程(module-tools)等。
+
+为了兼顾不同工程开发的差异和通性，Modern-js 将插件如下图进行组织:
+
+![plugin-relationship](https://lf3-static.bytednsdoc.com/obj/eden-cn/eeeh7uhbepxlpe/modern-website/plugin-relationship.jpg)
+
+从图可以看出，Modern-js 将插件大致分为两类:
+
+1. 通用插件: 插件只会包含一些基础的 Hooks
+
+2. 工程插件: 不同的工程开发会在通用插件的基础上扩展出自己的 Hooks, Config 等类型。
+
+使用 TypeScript 时，可以引入内置的 `CliPlugin` 等类型，为插件提供正确的类型推导。
 
 ```ts
 import type { CliPlugin } from '@modern-js/core';
@@ -54,19 +66,55 @@ const MyPlugin: CliPlugin = {
 };
 ```
 
-Modern.js 导出的 `Plugin` 类型支持泛型扩展。
+上述代码为通用插件，只包含一些基础的 Hooks。 Modern.js 支持通过泛型对插件的定义进行扩展：
+
+```ts
+import type { CliPlugin, AppTools } from '@modern-js/app-tools';
 
-在 Modern.js 中，任意插件可以注册自己的 Hook，如果想拥有其他插件注册的 Hook 的类型，可以添加泛型：
+const MyPlugin: CliPlugin<AppTools> = {
+  name: 'my-plugin',
+
+  setup() {
+    const foo = '1';
+
+    return {
+      afterBuild: () => {
+        // 在构建完成后执行逻辑
+      },
+    };
+  },
+};
+```
+
+如果仔细观察 `AppTools` 这个类型，可以发现 `AppTools` 由 3 种类型构成.
+
+```ts
+type AppTools = {
+  hooks: AppToolsHooks;
+  userConfig: AppToolsUserConfig;
+  normalizedConfig: AppToolsNormalizedConfig;
+};
+```
+
+当编写插件时，插件通过泛型扩展在不同的基础上扩展自己的 Hooks 等类型:
 
 ```ts
+// 通用插件上扩展
 import type { CliPlugin } from '@modern-js/core';
 import type { MyPluginHook } from 'xxx';
 
-const MyPlugin: CliPlugin<MyPluginHook> = {};
+const MyPlugin: CliPlugin<{ hooks: MyPluginHook }> = {};
 ```
 
-详细说明，请参考 [扩展 Hook](/docs/guides/topic-detail/framework-plugin/extend)。
+```ts
+// 在 @modern-js/app-tools 基础上扩展
+import type { CliPlugin, AppTools } from '@modern-js/app-tools';
+import type { MyPluginHook } from 'xxx';
+
+const MyPlugin: CliPlugin<AppTools & { hooks: MyPluginHook }> = {};
+```
 
+详细说明，请参考 [扩展 Hook](/docs/guides/topic-detail/framework-plugin/extend)。
 
 ### 插件配置项
 

package/zh/guides/topic-detail/micro-frontend/c02-development.md

@@ -179,7 +179,7 @@ export default () => <div>Table Page</div>;
 
 访问主应用地址 `http://localhost:8080`，效果如下：
 
-![demo](https://tosv.byted.org/obj/eden-internal/ozpmyhn_lm_hymuPild/ljhwZthlaukjlkulzlp/modernjs/micro-demo.gif)
+![demo](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/micro-demo.gif)
 
 在完成了微前端整体开发流程的体验后，你可以进一步了解如何 [开发主应用](./c03-main-app.md)
 

package/en/docusaurus-plugin-content-docs/current/configure/app/dev/with-master-app.md

@@ -1,31 +0,0 @@
----
-sidebar_label: withMasterApp
----
-
-# dev.withMasterApp
-
-* Type: `Object`
-* Default: `null`
-
-When the project is a micro-front-end sub-application, you can use the `withMasterApp` configuration to enable the sub-application debugging mode.
-
-:::caution Caution
-When using child app debugging mode, you should first ensure that the main app has online debugging mode turned on.
-:::
-
-```js title=modern.config.js
-export default defineConfig({
-  dev: {
-    withMasterApp: {
-      //the path of the main application
-      moduleApp: 'https://www.masterApp.com',
-      //name of the subapplication
-      moduleName: 'Contact'
-    }
-  }
-})
-```
-
-- moduleApp: `string` Online address of the main application.
-- moduleName: `Contact` The name of the child app (needs to match the module name registered in the main app)。
-

package/zh/configure/app/dev/with-master-app.md

@@ -1,32 +0,0 @@
----
-sidebar_label: withMasterApp
----
-
-# dev.withMasterApp
-
-
-
-* 类型： `Object`
-* 默认值： `null`
-
-当项目为微前端子应用的时候，可以使用 `withMasterApp` 配置启用子应用调试模式。
-
-:::caution 注意
-使用子应用调试的模式时，应该先确保主应用开启了线上 debug 模式。
-:::
-
-```js title=modern.config.js
-export default defineConfig({
-  dev: {
-    withMasterApp: {
-      // 主应用的路径
-      moduleApp: 'https://www.masterApp.com',
-      // 子应用的名称
-      moduleName: 'Contact'
-    }
-  }
-})
-```
-
-- moduleApp: `string` 主应用的线上地址。
-- moduleName: `Contact` 子应用的名称（需要和在主应用中注册的模块名匹配）。