@modern-js/main-doc 2.0.0-beta.4 → 2.0.0-beta.5

package/zh/guides/topic-detail/micro-frontend/c01-introduction.md

@@ -0,0 +1,29 @@
+---
+sidebar_position: 1
+title: 微前端介绍
+---
+
+微前端是一种类似于微服务的架构，是一种由独立交付的多个前端应用组成整体的架构风格，将前端应用分解成一些更小、更简单的能够独立开发、测试、部署的应用，而在用户看来仍然是内聚的单个产品。
+
+它主要解决了两个问题：
+
+* 随着项目迭代应用越来越庞大，难以维护。
+* 跨团队或跨部门协作开发项目导致效率低下的问题。
+
+## 微前端关键词
+
+在微前端研发模式中，应用会被分成 **主应用**、和 **子应用**。
+
+- 主应用：微前端项目的基座工程，所有子应用都会由它来加载。
+- 子应用：独立开发、独立部署的应用，最终会被主应用加载。
+
+## 功能简介
+
+* 基于 [Garfish](https://www.garfishjs.org/guide)
+* 生成器支持微前端应用
+* 支持 React 组件式引用微前端子应用
+* 支持 loading
+* 支持主应用线上、子应用线下调试模式
+
+可以在 [体验微前端](/docs/guides/topic-detail/micro-frontend/c02-development) 一节学习如何开发微前端主子应用。
+

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

@@ -0,0 +1,191 @@
+---
+sidebar_position: 2
+title: 体验微前端
+---
+
+通过本章你可以了解到：
+
+- 如何创建微前端项目的主应用、子应用。
+- 微前端项目开发的基本流程。
+
+## 创建应用
+
+在这次的实践中，我们需要创建三个应用，分别为1个主应用，2个子应用：
+
+- main 主应用
+- dashboard 子应用
+- table 子应用
+
+### 创建 main 主应用
+
+通过命令行工具初始化项目：
+
+```bash
+mkdir main && cd main
+npx @modern-js/create
+```
+
+import DefaultMWAGenerate from '@site-docs/components/default-mwa-generate.md';
+
+<DefaultMWAGenerate />
+
+完成项目创建后我们可以通过 `pnpm run new` 来开启 `微前端` 功能：
+
+```bash
+? 请选择你想要的操作 启用可选功能
+? 启用可选功能 启用「微前端」模式
+```
+
+接下来，让我们注册微前端插件并添加开启微前端主应用，并增加子应用列表：
+
+import EnableMicroFrontend from '@site-docs/components/enable-micro-frontend.md';
+
+<EnableMicroFrontend />
+
+import MicroRuntimeConfig from '@site-docs/components/micro-runtime-config.md';
+
+<MicroRuntimeConfig />
+
+
+### 创建 dashboard 子应用
+
+通过命令行工具初始化项目：
+
+```bash
+mkdir dashboard && cd dashboard
+npx @modern-js/create
+```
+
+按照如下选择，生成项目：
+
+<DefaultMWAGenerate/>
+
+我们执行 `pnpm run new` 来开启 `微前端` 功能：
+
+```bash
+? 请选择你想要的操作 启用可选功能
+? 启用可选功能 启用「微前端」模式
+```
+接下来，让我们注册微前端插件并修改 `modern.config.ts`，添加微前端子应用的配置 `deploy.microFrontend`：
+
+```javascript title="modern.config.ts"
+import AppToolPlugin, { defineConfig } from '@modern-js/app-tools';
+import GarfishPlugin from '@modern-js/plugin-garfish';
+
+export default defineConfig({
+  runtime: {
+    router: true,
+    state: true
+  },
+  deploy: {
+    microFrontend: true
+  },
+  plugins: [AppToolPlugin(), GarfishPlugin()],
+});
+```
+
+### 创建 table 子应用
+
+通过命令行工具初始化项目：
+
+```bash
+mkdir table && cd table
+npx @modern-js/create
+```
+
+按照如下选择，生成项目：
+
+<DefaultMWAGenerate/>
+
+我们执行 `pnpm run new` 来开启 `微前端`：
+
+```bash
+? 请选择你想要的操作 启用可选功能
+? 启用可选功能 启用「微前端」模式
+```
+
+接下来，让我们注册微前端插件并修改 `modern.config.ts`，添加微前端子应用的配置 `deploy.microFrontend`：
+
+```javascript title="modern.config.ts"
+import AppToolPlugin, { defineConfig } from '@modern-js/app-tools';
+import GarfishPlugin from '@modern-js/plugin-garfish';
+
+export default defineConfig({
+  runtime: {
+    router: true,
+    state: true
+  },
+  deploy: {
+    microFrontend: true
+  },
+  plugins: [AppToolPlugin(), GarfishPlugin()],
+});
+```
+
+## 添加代码
+
+### main 主应用
+
+删除 `src/routers` 目录, 创建 `src/App.tsx`，并添加如下内容：
+
+```tsx
+import { Link } from '@modern-js/runtime/router';
+import { useModuleApps } from '@modern-js/runtime/garfish';
+
+const App = () => {
+  const { DashBoard, TableList } = useModuleApps();
+  return (
+    <div>
+      <div>
+        <Link to='/dashboard'>Dashboard</Link> &nbsp;
+        <Link to='/table'>Table</Link>
+      </div>
+      <Route path='/dashboard'>
+        <DashBoard />
+      </Route>
+      <Route path='/table'>
+        <TableList />
+      </Route>
+    </div>
+  );
+};
+
+export default App;
+```
+
+### dashboard 子应用
+
+删除 `src/routers` 目录, 创建 `src/App.tsx`，并添加如下内容：
+
+```tsx
+export default () => <div>Dashboard Page</div>;
+```
+
+### table 子应用
+
+删除 `src/routers` 目录, 创建 `src/App.tsx`，并添加如下内容：
+
+```tsx
+export default () => <div>Table Page</div>;
+```
+
+## 调试
+
+按顺序在 `main`、 `dashboard`、 `table` 目录执行 `pnpm run dev` 命令启动应用：
+
+- main      - `http://localhost:8080`
+- dashboard - `http://localhost:8081`
+- table     - `http://localhost:8082`
+
+访问主应用地址 `http://localhost:8080`，效果如下：
+
+![demo](https://tosv.byted.org/obj/eden-internal/ozpmyhn_lm_hymuPild/ljhwZthlaukjlkulzlp/modernjs/micro-demo.gif)
+
+在完成了微前端整体开发流程的体验后，你可以进一步了解如何 [开发主应用](./c03-main-app.md)
+
+
+## 常见问题
+
+自查手册: https://www.garfishjs.org/issues/
+
+

package/zh/guides/topic-detail/micro-frontend/c03-main-app.md

@@ -0,0 +1,246 @@
+---
+sidebar_position: 3
+title: 开发主应用
+---
+
+在上一章 [体验微前端](./c02-development.md) 通过一个示例演示了如何创建和配置微前端子应用，通过本章你可以进一步了解如何开发主应用，以及它的常见配置。
+
+在通过 `@modern-js/create` 命令创建应用工程后，可以在项目中执行 `pnpm run new`（实际执行了 `modern new` 命令），在选择了「微前端」模式后，会安装微前端依赖依赖，只需手动注册插件即可。
+
+import EnableMicroFrontend from '@site-docs/components/enable-micro-frontend.md';
+
+<EnableMicroFrontend />
+
+## 注册子应用信息
+
+当在 `masterApp` 配置上提供了信息后，将会认为该应用为主应用，目前存在两种子应用信息的配置方式，这两种方式分别应用于不同的场景。
+
+
+### 直接注册子应用信息
+
+可以直接通过配置注册子应用信息：
+
+:::tip 提示
+可以通过 API [defineConfig](/docs/apis/app/runtime/app/define-config) 在运行时进行配置。
+当参数为函数时无法被序列化到产物代码，所以在涉及到函数之类的配置时请通过 defineConfig 来进行配置
+:::
+
+import MicroRuntimeConfig from '@site-docs/components/micro-runtime-config.md';
+
+<MicroRuntimeConfig />
+
+
+### 自定义远程应用列表
+
+通过该函数可以拉取远程的子应用列表，并将其注册至运行时框架：
+
+```ts title="App.tsx"
+defineConfig(App, {
+  masterApp: {
+    manifest: {
+      getAppList: async ()=> {
+        // 可以从其他远程接口获取
+        return [
+            {
+              name: 'DashBoard',
+              entry: 'http://127.0.0.1:8081/'
+            },
+            {
+              name: 'TableList',
+              entry: 'http://localhost:8082'
+            }
+        ];
+      },
+    }
+  }
+})
+```
+
+## 渲染子应用
+
+在微前端中分为两种加载子应用的方式：
+
+1. **子应用组件** 获取到每个子应用的组件，之后就可以像使用普通的 `React` 组件一样渲染微前端的子应用。
+2. **集中式路由** 通过集中式的路由配置，自动根据当前页面 `pathname` 激活渲染对应的子应用。
+
+### 子应用组件
+
+开发者使用 `useModuleApps` 方法可以获取到各个子应用的组件。
+
+再通过 `router` 组件的结合运用，开发者可以自控式的根据不同的路由渲染不同的子应用。
+
+假设我们的子应用列表配置如下：
+
+<EnableMicroFrontend />
+
+编辑主应用 `App.tsx` 文件如下：
+
+```tsx title=主应用：App.tsx
+import { useModuleApps } from '@modern-js/runtime/garfish';
+import { Route, Switch } from '@modern-js/runtime/router';
+
+function App() {
+  const { DashBoard, TableList} = useModuleApps();
+
+  return <div>
+    <Route path="/dashboard">
+      <DashBoard
+        loadable={{
+          loading: ({ pastDelay, error }: any) => {
+            if (error) {
+              return <div>error: {error?.message}</div>;
+            } else if (pastDelay) {
+              return <div>loading</div>;
+            } else {
+              return null;
+            }
+          },
+        }}
+      />
+    </Route>
+    <Route path="/table">
+      <TableList />
+    </Route>
+  </div>
+}
+```
+
+这里通过 `Route` 组件自定义了 **DashBoard** 的激活路由为 **/dashboard**， **TableList** 的激活路由为 **/table**。
+
+### 集中式路由
+
+**集中式路由** 是将子应用的激活路由集中配置的方式。我们给子应用列表信息添加 `activeWhen` 字段来启用 **集中式路由**。
+
+
+<MicroRuntimeConfig />
+
+然后在主应用中使用 `useModuleApp` 方法获取 `MApp` 组件, 并在主应用渲染 `MApp`。
+
+```tsx title=主应用：App.tsx
+import { useModuleApp } from '@modern-js/plugin-runtime';
+
+function App() {
+  const { MApp } = useModuleApps();
+
+  return <div>
+    <MApp />
+  </div>
+}
+```
+
+这样启动应用后，访问 `/dashboard` 路由，会渲染 `Dashboard` 子应用，访问 `/table` 路由，会渲染 `TableList` 子应用。
+
+
+### 两种模式混用
+
+当然 **子应用组件** 和 **集中式路由** 是可以混合使用的。
+
+- 一部分子应用作为 **子应用组件** 激活，另外一部分作为 **集中式路由** 激活。
+- 一部分子应用既可以作为 **集中式路由** 激活，也可以作为 **子应用组件** 激活。
+
+
+### 添加 loading
+
+通过配置 `loadable` 配置，可以为「集中式路由」、「子应用」添加 loading 组件，并可以考虑错误、超时、闪烁等情况的出现，从而为用户提供更好的用户体验。该功能的设计与实现参考至 [react-loadable](https://github.com/jamiebuilds/react-loadable)，基本功能较为相似。
+
+```tsx
+function Loading() {
+  return <div>Loading...</div>;
+}
+
+function App(){
+  return <>
+    <DashBoard
+      loadable={{
+        loading: Loading,
+      }}
+    />
+  <>
+}
+```
+
+#### 增加错误状态
+
+当微前端子应用加载失败或渲染失败时，`loading component` 将会接收 `error` 参数（若没有错误时 error 是 null）
+
+```tsx
+function Loading({ error }) {
+  if (error) {
+    return <div>Error msg {error?.message}</div>;
+  } else {
+    return <div>Loading...</div>;
+  }
+}
+```
+
+#### 避免 loading 闪退
+
+有时 loading 组件的显示时间可能小于 200ms，这个时候会出现 loading 组件闪退的情况。许多用户研究证明，loading 闪退的情况会导致用户感知加载内容的耗时比实际耗时更长，在 loading 小于 200ms 时，不展示内容，用户会认为它更快。
+
+所以 loading 组件还提供了 `pastDelay` 参数，超过设置的延迟展示时才会为 true，可以通过 `delay` 参数设置延迟的时长
+
+
+```tsx
+function Loading({ error, pastDelay }) {
+  if (error) {
+    return <div>Error! {error?.message}</div>;
+  } else if (pastDelay) {
+    return <div>Loading...</div>;
+  } else {
+    return null;
+  }
+}
+```
+
+`delay` 的默认值为 `200ms`，可以通过 `loadable` 中的 `delay` 来设置延迟展示的时间
+
+```tsx
+
+function App(){
+  return <>
+    <DashBoard
+      loadable={{
+        loading: Loading,
+        delay: 300 // 0.3 seconds
+      }}
+    />
+  <>
+}
+```
+
+#### 增加超时状态
+
+有时因为网络的原因，从而导致微前端子应用加载失败，从而导致一直展示 loading 的状态，这对于用户而言非常糟糕，因为他们不知道合适才会获得具体的响应，他们是否需要刷新页面，通过增加超时状态可以很好的解决该问题。
+
+loading 组件在超时时会获得 `timeOut` 参数，当微前端应用加载超时时将会获得 `timeOut` 属性值为 true
+
+```tsx
+function Loading({ error, timeOut, pastDelay }) {
+  if (error) {
+    return <div>Error! {error?.message}</div>;
+  } else if (timeOut) {
+    return <div>Loading timed out, please refresh the page... </div>;
+  } else if (pastDelay) {
+    return <div>Loading...</div>;
+  } else {
+    return null;
+  }
+}
+```
+
+超时状态是关闭的，可以通过在 `loadable` 中设置 `timeout` 参数开启
+
+
+```tsx
+
+function App(){
+  return <>
+    <DashBoard
+      loadable={{
+        loading: Loading,
+        timeOut: 10000 // 10s
+      }}
+    />
+  <>
+}
+```

package/zh/guides/topic-detail/micro-frontend/c04-communicate.md

@@ -0,0 +1,54 @@
+---
+sidebar_position: 4
+title: 主子应用通信
+---
+
+## props 通信
+
+Modern.js 中，会将子应用包裹成一个 React 组件，直接通过给 React 组件传递 `props` 即可实现主应用和子应用通信的目的。
+
+```tsx title=主应用：App.tsx
+function App() {
+  const { MApp } = useModuleApps();
+
+  return <div>
+    <MApp count={100} />
+  </div>;
+}
+```
+
+```tsx title=子应用：App.tsx
+function App(props) {
+  console.log(props);
+  return ...
+}
+```
+
+子应用将会打印 `{count: 0}`，目前尚未支持子应用渲染响应式，及时在主应用上更改 `count` 的数据也不会触发视图更新
+
+## channel 通信
+
+[Garfish.channel](https://www.garfishjs.org/api/channel) 用于应用间的通信。它是 `EventEmitter2` 的实例
+
+```ts
+// 子应用监听登录事件
+const App = () => {
+  const handleLogin = (userInfo) => {
+    console.log(`${userInfo.name} has login`);
+  };
+
+  useEffect(() => {
+    window?.Garfish.channel.on('login', handleLogin);
+    return () => {
+      window?.Garfish.channel.removeListener('login', handleLogin);
+    };
+  });
+};
+
+// 主应用触发监听事件
+api.getLoginInfo.then((res) => {
+  if (res.code === 0) {
+    window.Garfish.channel.emit('login', res.data);
+  }
+});
+```

package/zh/guides/topic-detail/micro-frontend/{mixed-stack.md → c05-mixed-stack.md}

@@ -3,7 +3,7 @@ sidebar_position: 5
 title: 混合技术栈
 ---
 
-Modern.js 微前端方案是基于 [Garfish](https://garfish.top/) 封装的，提供了一些更开箱即用的使用方式。
+Modern.js 微前端方案是基于 [Garfish](https://garfishjs.org/) 封装的，提供了一些更开箱即用的使用方式。
 
 当你的主应用和子应用不全是 Modern.js 应用的时候，可以参考这片文档。
 
@@ -12,7 +12,7 @@ Modern.js 微前端方案是基于 [Garfish](https://garfish.top/) 封装的，
 
 ## 子应用是 Modern.js
 
-**Modern.js** 子应用编译后会生成标准的 [Garfish 子应用导出](https://garfish.top/quick-start#%E5%AD%90%E5%BA%94%E7%94%A8)。
+**Modern.js** 子应用编译后会生成标准的 [Garfish 子应用导出](https://www.garfishjs.org/guide/start#2%E5%AF%BC%E5%87%BA-provider-%E5%87%BD%E6%95%B0)。
 所以可以直接接入标准的微前端主应用。
 
 :::info 注
@@ -21,4 +21,4 @@ Modern.js 微前端方案是基于 [Garfish](https://garfish.top/) 封装的，
 
 ## 主应用是 Modern.js
 
-主应用是 **Modern.js**，子应用用的其它技术栈。子应用按照 [Garfish 子应用标准](https://garfish.top/quick-start#%E5%AD%90%E5%BA%94%E7%94%A8) 开发即可。
+主应用是 **Modern.js**，子应用用的其它技术栈。子应用按照 [Garfish 子应用标准](https://www.garfishjs.org/guide/demo/react) 开发即可。

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

@@ -57,8 +57,8 @@ pnpm run new
 [INFO] 创建成功！
 可在新项目的目录下运行以下命令：
 pnpm run dev          # 按开发环境的要求，运行和调试项目
-pnpm run build        # 按产品环境的要求，构建项目
-pnpm run start        # 按产品环境的要求，运行项目
+pnpm run build        # 按生产环境的要求，构建项目
+pnpm run serve        # 按生产环境的要求，运行项目
 pnpm run lint         # 检查和修复所有代码
 pnpm run new          # 继续创建更多项目要素，比如应用入口
 ```

package/zh/tutorials/first-app/c01-start.md

@@ -64,20 +64,24 @@ function App() {
 export default App;
 ```
 
-因为框架默认支持 [HMR](https://webpack.js.org/concepts/hot-module-replacement/)，可以看到 `http://localhost:8080/` 里的内容会自动变成 Hello Modern.js。
-
 删除多余的 css 文件，保持目录没有多余的文件：
 
 ```bash
 rm src/routes/index.css
 ```
 
-## 使用配置
+因为框架默认支持 [HMR](https://webpack.js.org/concepts/hot-module-replacement/)，可以看到 `http://localhost:8080/` 里的内容会自动更新为：
+
+![result](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvt/ljhwZthlaukjlkulzlp/screenshot-20221214-141909.png)
+
+此刻的页面还没有样式。下一章节将展开这部分的内容。
+
+## 开启 SSR
 
 接下来，我们修改项目中的 `modern.config.ts`，开启 SSR 能力：
 
 ```ts
-import { defineConfig } from '@modern-js/app-tools';
+import AppToolsPlugin, { defineConfig } from '@modern-js/app-tools';
 
 // https://modernjs.dev/docs/apis/app/config
 export default defineConfig({
@@ -88,6 +92,7 @@ export default defineConfig({
   server: {
     ssr: true,
   },
+  plugins: [AppToolsPlugin()],
 });
 ```
 

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

@@ -118,6 +118,25 @@ Modern.js 集成了主流、轻量、通用的 Utility Class 工具库 [Tailwind
 ? 启用可选功能 启用 Tailwind CSS 支持
 ```
 
+在 `modern.config.ts` 中注册 Tailwind 插件:
+
+```ts title="modern.config.ts"
+import AppToolsPlugin, { defineConfig } from '@modern-js/app-tools';
+import TailwindCSSPlugin from '@modern-js/plugin-tailwindcss';
+
+// https://modernjs.dev/docs/apis/app/config
+export default defineConfig({
+  runtime: {
+    router: true,
+    state: true,
+  },
+  server: {
+    ssr: true,
+  },
+  plugins: [AppToolsPlugin(), TailwindCSSPlugin()],
+});
+```
+
 在 `src/routes/page.tsx` 顶部引入 Tailwind CSS 的 css 文件，就可以开始快速实现专业的 UI：
 
 ```js

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

@@ -34,7 +34,7 @@ ni src/routes/archives/page.tsx
 
 添加如下代码：
 
-```tsx
+```tsx title="src/archives/page.tsx"
 import { List } from 'antd';
 import { Helmet } from '@modern-js/runtime/head';
 import Item from '../../components/Item';
@@ -94,16 +94,16 @@ Modern.js 默认集成了 react-helmet，也可以结合 SSR 使用，满足 SEO
 import 'tailwindcss/base.css';
 import 'tailwindcss/components.css';
 import 'tailwindcss/utilities.css';
-import "../styles/utils.css";
+import '../styles/utils.css';
 ```
 
 执行 `pnpm run dev`，访问 `http://localhost:8080`，可以看到完整的联系人，页面的标题是 All：
 
-![display](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c04-all.png)
+![display1](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c04-archives.png)
 
 访问 `http://localhost:8080/archives`，只会看到已存档的联系人，页面的标题是 Archives：
 
-![display1](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c04-archives.png)
+![display](https://lf3-static.bytednsdoc.com/obj/eden-cn/nuvjhpqnuvr/modern-website/tutorials/c04-all.png)
 
 查看页面 HTML 源码，可以看到两个页面的内容是一样，是在客户端针对不同 URL 渲染不同内容。
 

package/zh/tutorials/first-app/c05-loader.md

@@ -4,7 +4,7 @@ title: 添加 Loader
 
 上一章节中，我们学习了如何添加客户端路由。
 
-这一章节中，我们将会学习如何**为路由组件添加 Loader**。
+这一章节中，我们将会学习如何为**路由组件添加 Loader**。
 
 到目前为止，我们都是通过硬编码的方式，为组件提供数据。如果要从远端获取数据，通常情况下会使用 `useEffect` 来做。但在启用 SSR 的情况下，`useEffect` 是不会在服务端执行的，所以这种 SSR 只能渲染很有限的 UI。
 
@@ -20,7 +20,7 @@ pnpm add @types/faker@5 -D
 修改 `src/routes/page.tsx`：
 
 ```tsx
-import { name, internet } from "faker";
+import { name, internet } from 'faker';
 
 type LoaderData = {
   code: number;
@@ -55,7 +55,7 @@ Data Loader 并非只为 SSR 工作。在 CSR 项目中，Data Loader 也可以
 Modern.js 也提供了一个叫 `useLoaderData` 的 hooks API，我们修改 `src/routes/page.tsx` 导出的组件：
 
 ```tsx {1,4,13}
-import { useLoaderData } from "@modern-js/runtime/router";
+import { useLoaderData } from '@modern-js/runtime/router';
 
 function Index() {
   const { data } = useLoaderData() as LoaderData;