@modern-js/main-doc 2.0.0-canary.0 → 2.0.0

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/generator/config/common.md

@@ -47,7 +47,7 @@ Package management tool (packageManager), the options are as follows:
 In the custom type of the generator plugin to create a project scenario, only the `packageManager` configuration is provided by default.
 :::
 
-## 其他配置
+## Other configurations
 
 ### noNeedInstall
 

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/generator/config/module.md

@@ -14,7 +14,7 @@ The application project creation parameters are [Generator Configuration](/docs/
 
 Package name (packageName), character string type.
 
-## New 命令
+## New Command
 
 The new command configuration in the module project can be used through the `--config` parameter configuration when executing the new command, or when enabling functions in the generator plugin.
 
@@ -37,3 +37,5 @@ Optional function name (function), supports the following options:
 - Storybook(mwa_storybook)
 
 - Runtime API(runtimeApi)
+
+- Test(test)

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/generator/config/mwa.md

@@ -34,20 +34,12 @@ Element name (element), supports two options:
 
 - Create customized server dir(server)
 
-These two options also need to be used in conjunction with the specific configuration, which is described as follows:
+The entry also need to be used in conjunction with the specific configuration, which is described as follows:
 
 #### name
 
 Entry name (name), character `string` type.
 
-#### framework
-
-Customized server runtime framework(framework)，supports two options:：
-
-- Express(express)
-
-- Koa(koa)
-
 ### function
 
 Optional function name (function), supports the following options:

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/generator/project.md

@@ -24,7 +24,7 @@ Use npx to get the latest version of `@modern-js/create` every time.
 
 Project directory name.
 
-When executing the above command, the 'projectDir` folder will be created in the current directory by default, and the initialization project will be in this folder. When this parameter is empty, the initialization project will be directly generated in the current directory.
+When executing the above command, the `projectDir` folder will be created in the current directory by default, and the initialization project will be in this folder. When this parameter is empty, the initialization project will be directly generated in the current directory.
 
 ### --version
 
@@ -104,7 +104,7 @@ For custom generator plugins, please refer to [Development Generator Plugin](/do
 
 Specifies the microgenerator.
 
-By default, `@modern-js/create` will execute the microgenerator Modern.js framework build-in. If you need to execute a customized microgenerator, and you need to use the posture of'npx @modern-js/create ', you can use this parameter directly.
+By default, `@modern-js/create` will execute the microgenerator Modern.js framework build-in. If you need to execute a customized microgenerator, and you need to use the posture of `npx @modern-js/create`, you can use this parameter directly.
 
 For custom microgenerators, please refer to [Develop Microgenerator](/docs/guides/topic-detail/generator/codesmith/introduce).
 

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/micro-frontend/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Micro Frontend",
+  "position": 2
+}

package/en/docusaurus-plugin-content-docs/current/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/en/docusaurus-plugin-content-docs/current/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/plugin-garfish/runtime';
+
+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://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/micro-demo.gif)
+
+在完成了微前端整体开发流程的体验后，你可以进一步了解如何 [开发主应用](./c03-main-app.md)
+
+
+## 常见问题
+
+自查手册: https://www.garfishjs.org/issues/
+
+

package/en/docusaurus-plugin-content-docs/current/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/plugin-garfish/runtime';
+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/en/docusaurus-plugin-content-docs/current/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/en/docusaurus-plugin-content-docs/current/guides/topic-detail/micro-frontend/c05-mixed-stack.md

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

package/en/docusaurus-plugin-content-docs/current/guides/topic-detail/model/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Reduck State Manage",
+  "position": 1
+}