@modern-js/main-doc 0.0.0-next-20221116121040

package/zh/guides/topic-detail/micro-frontend/debugging.md

@@ -0,0 +1,168 @@
+---
+sidebar_position: 2
+title: 子应用调试
+---
+
+根据研发的不同阶段，我们将子应用调试分为如下两种方式：
+
+1. 使用本地主应用调试。
+2. 使用线上主应用调试。
+
+## 使用本地主应用调试
+
+项目初期，主应用未部署，可以使用本地分别启动主应用、子应用的方式进行调试。
+
+### 主应用
+
+#### 配置
+
+```js title="modern.config.js"
+export default defineConfig({
+  runtime: {
+    router: true,
+    masterApp: {
+      manifest: {
+        modules: [
+          {
+            name: 'Dashboard',
+            entry: 'http://localhost:8081',
+          },
+        ],
+      },
+    },
+  },
+});
+```
+
+假设本地的子应用的名字为 `DashBoard` 且启动服务的地址为 `http://localhost:8081`。配置 `runtime.masterApp.modules` 字段指定子应用的相关信息。
+
+#### 加载子应用
+
+使用 [useModuleApps](/docs/apis/app/runtime/app/use-module-apps) API 获取子应用组件，并加载子应用。
+
+```tsx title=App.tsx
+import { useModuleApps } from '@modern-js/plugin-garfish';
+
+function App() {
+  const { Dashboard } = useModuleApps();
+
+  return (
+    <div>
+      Master APP
+      <Route path="/dashboard">
+        <Dashboard />
+      </Route>
+    </div>
+  );
+}
+```
+
+### 子应用
+
+#### 配置
+
+```js title="modern.config.js"
+export default defineConfig({
+  deploy: {
+    microFrontend: true,
+  },
+});
+```
+
+当 `deploy.microFrontend` 字段配置为 true 的时候，Modern.js 将认为当前应用是一个微前端子应用，并将其编译为符合 Garfish 子应用规范的产物。
+
+#### 子应用代码
+
+子应用在代码层面和应用工程是完全一致的。
+
+```tsx title=src/App.tsx
+function App() {
+  return <div>dashboard</div>;
+}
+```
+
+:::info 注
+目前不支持在子应用中使用 BFF 功能。
+:::
+
+然后分别启动主应用和子应用（执行 `pnpm dev`），主应用访问 `8080` 端口，子应用访问 `8081` 端口。浏览器打开 `http://localhost:8080/dashboard` 就能看到加载了 `Dashboard` 子应用的效果了。
+
+## 使用线上主应用调试
+
+当主应用项目部署之后，Modern.js 提供了用线上主应用调试本地子应用的方式。
+
+:::info 注
+本小节所用线上地址均是虚构，只为演示方便。
+:::
+
+### 主应用
+
+#### 配置
+
+```js title="modern.config.js"
+export default defineConfig({
+  server: {
+    enableMicroFrontendDebug: true,
+  },
+  runtime: {
+    router: true,
+    masterApp: {
+      manifest: {
+        modules: [
+          {
+            name: 'Dashboard',
+            entry: 'http://modern-js.dev/dashboard',
+          },
+        ],
+      },
+    },
+  },
+});
+```
+
+:::info 注
+`enableMicroFrontendDebug` 会在线上开启 微前端 Debug 模式，如担心安全隐患，可只在线上测试环境开启，线上正式环境关掉该配置。
+:::
+
+### 子应用
+
+#### 配置
+
+```js title="modern.config.js"
+export default defineConfig({
+  deploy: {
+    microFrontend: true,
+  },
+});
+```
+
+本地启动子应用，其端口为 `8080`。
+
+### Query 模式调试
+
+访问主应用地址 `http://master.example.com/` 并在 URL 后加上 Query `?__debug__micro-frontend-debug-name=TableList&__debug__micro-frontend-debug-entry=http://localhost:8080`。
+
+此时访问主应用后，服务端注入的子应用模块信息将被替换为我们 Query 里的信息。即 `TableList` 子应用 `entry` 为 `http://localhost:8080`。线上主应用切换到 `/tablelist` 路由后将会加载本地的子应用。
+
+![query-debug](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/query-debug.png)
+
+### Header 模式调试（推荐）
+
+Query 调试时，当路透跳转的时候，Query 参数会丢失，reload 页面后，服务端返回的子应用信息里将不会注入本地的子应用信息。可以使用 Header 模式来调试，获取更稳定的调试开发体验。
+
+#### 环境要求
+
+[ModHeader](https://modheader.com/install) 是用于 Mock 浏览器请求/返回 Header 的浏览器插件。使用 ModHeader 支持的浏览器（Chrome、Firefox、Opera、Edge），并安装 ModHeader 插件。
+
+#### 配置 Header
+
+配置如下 Header:
+
+- `x-micro-frontend-module-name TableList`
+- `x-micro-frontend-module-entry http://localhost:8080`
+
+访问主应用地址如下所示
+
+![header-debug](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/header-debug.png)
+
+可以看到此时服务端返回的 `TableList` 子应用信息是 Header 里面指定的本地域名 `http://localhost:8080`

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

@@ -0,0 +1,13 @@
+---
+sidebar_position: 1
+title: 微前端介绍
+---
+
+随着前端生态的繁重以及 Web 应用日益复杂化，给大型项目研发流程、跨团队协作等带来不小的挑战。微前端从架构层面出发将多个独立交付的前端应用组成整体，这些前端应用能够「独立开发」、「独立测试」、「独立部署」，但是最终在用户看来仍然是内聚的单个产品。
+
+[Garfish](https://garfish.top/guide/) 是业界成熟的微前端解决方案，Modern.js 中开箱即用的支持了 [Garfish](https://garfish.top/guide/)。
+
+在微前端研发模式中，应用会被分成 **主应用**、和 **子应用**。
+
+- 主应用：微前端项目的基座工程，所有子应用都会由它来加载。
+- 子应用：独立开发、独立部署的应用，最终会被主应用加载。

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

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

package/zh/guides/topic-detail/micro-frontend/route-mode.md

@@ -0,0 +1,110 @@
+---
+sidebar_position: 4
+title: 加载子应用
+---
+
+在微前端中分为两种加载子应用的方式：
+
+1. **子应用组件** 获取到每个子应用的组件，之后就可以像使用普通的 React 组件一样渲染微前端的子应用。
+2. **集中式路由** 通过集中式的路由配置，自动根据当前页面 pathname 激活渲染对应的子应用。
+
+## 子应用组件
+
+使用 `useModuleApps` API 可以获取到各个子应用的组件。结合 `router`，可以自控式的根据不同的路由渲染不同的子应用。
+
+假设我们的子应用列表配置如下：
+
+```js title="modern.config.js"
+export default defineConfig({
+  runtime: {
+    masterApp: {
+      manifest: {
+        modules: [
+          {
+            name: "Dashboard",
+            entry: "http://localhost:8081"
+          },
+          {
+            name: "TableList",
+            entry: "http://localhost:8082"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+编辑主应用 `App.tsx` 文件如下：
+
+```tsx title=主应用：App.tsx
+import { useModuleApps } from '@modern-js/plugin-garfish';
+import { Route, Switch } from '@modern-js/runtime/router';
+
+function App() {
+  const { Dashboard, TableList } = useModuleApps();
+
+  return <div>
+    <Switch>
+      <Route path='/dashboard'>
+        <Dashboard />
+      </Route>
+      <Route path='/tablelist'>
+        <TableList />
+      </Route>
+    </ Switch>
+  </div>
+}
+```
+
+这里通过 `Route` 组件自定义了 **DashBoard** 的激活路由为 **/dashboard**， **TableList** 的激活路由为 **/tablelist**。
+
+## 集中式路由
+
+**集中式路由** 是将子应用的激活路由集中配置的方式。我们给子应用列表信息添加 `activeWhen` 字段来启用 **集中式路由**。
+
+```js title="modern.config.js"Å {8,13}
+export default defineConfig({
+  runtime: {
+    masterApp: {
+      manifest: {
+        modules: [
+          {
+            name: "Dashboard",
+            activeWhen: '/dashboard',
+            entry: "http://localhost:8081"
+          },
+          {
+            name: TableList,
+            activeWhen: '/tablelist',
+            entry: "http://localhost:8082"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+然后在主应用中使用 `useModuleApp` API 来获取 `MApp` 在主应用渲染。
+
+```tsx title=主应用：App.tsx
+import { useModuleApp } from '@modern-js/runtime';
+
+function App() {
+  const MApp = useModuleApp();
+
+  return <div>
+    <MApp />
+  </div>
+}
+```
+
+这样启动应用后，访问 `/dashboard` 路由，会渲染 `Dashboard` 子应用，访问 `/tablelist` 路由，会渲染 `TableList` 子应用。
+
+## 两种模式混用
+
+当然 **子应用组件** 和 **集中式路由** 是可以混合使用的。
+
+- 一部分子应用作为 **子应用组件** 激活，另外一部分作为 **集中式路由** 激活。
+- 一部分子应用既可以作为 **集中式路由** 激活，也可以作为 **子应用组件** 激活。

package/zh/guides/topic-detail/model/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Reduck 状态管理",
+  "position": 1
+}

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

@@ -0,0 +1,90 @@
+---
+sidebar_position: 6
+title: 自动生成 Actions
+---
+
+在 [快速上手](/docs/guides/topic-detail/model/quick-start) 中，我们实现最简单的计数器 Model 也需要 10 行代码。
+实际上，Modern.js 支持根据声明的 `state` 类型，自动生成常用的 Actions，从而简化模板代码量。当前支持的类型有：
+
+- 原始数据类型
+- 数组类型
+- 简单对象类型（Plain Object）
+
+## 原始数据类型
+
+```ts
+const countModel = model('count').define({ state: 1 });
+```
+
+如上我们仅用一行就完成了一个简单的 `countModel`。使用 Model 的示例代码如下：
+
+```tsx
+function Counter() {
+  const [state, actions] = useModel(countModel);
+
+  useEffect(() => {
+    // 增加 1
+    actions.setState(state + 1);
+  }, []);
+}
+```
+
+## 数组类型
+
+当 State 为数组类型时，自动生成 Actions 的示例代码如下：
+
+```ts
+const countModel = model('count').define({ state: [] });
+
+function Counter() {
+  const [state, actions] = useModel(countModel);
+
+  useEffect(() => {
+    actions.push(1);
+    actions.pop();
+    actions.shift();
+    actions.unshift(1);
+    actions.concat([1]);
+    actions.splice(0, 1, 2);
+    actions.filter(value => value > 1);
+  }, []);
+}
+```
+
+我们可以使用 JavaScript Array 对象的方法，修改 State。
+
+## 简单对象类型
+
+当 State 为简单对象类型时，自动生成 Actions 的示例代码如下：
+
+```ts
+const countModel = model('count').define({
+  state: {
+    a: 1,
+    b: [],
+    c: {},
+  },
+});
+
+function Counter() {
+  const [state, actions] = useModel(countModel);
+
+  useEffect(() => {
+    actions.setA(2);
+    actions.setB([1]);
+    actions.setC({ a: 1 });
+  }, []);
+}
+```
+
+根据 `a`、`b`、`c` 三个不同的字段分别生成 `setA`、`setB`、`setC` 三个 Actions。
+
+:::info 注
+当用户自定义的 Action 和 Modern.js 自动生成的 Action 名字一致时，用户自定义的 Action 优先级更高。例如，
+在 `countModel` 中已经自定义 `setA` 这个 Action，调用 `actions.setA()` 时，最终执行的是用户自定义的 `setA`。
+:::
+
+
+:::info 补充信息
+相关 API 的更多介绍，请参考[这里](/docs/apis/app/runtime/model/auto-actions)。
+:::

package/zh/guides/topic-detail/model/computed-state.md

@@ -0,0 +1,151 @@
+---
+sidebar_position: 4
+title: 衍生状态
+---
+
+一些场景中，组件需要对 Model 中的 State 进行进一步计算，才能在组件中使用，这部分逻辑可以直接写在组件内部，也可以通过 Model 的衍生状态实现。
+衍生状态定义在 Model 中的 `computed` 字段下。根据依赖的 Model 的不同、返回类型的不同，衍生状态的定义方法可以分为以下 3 种。
+
+
+## 只依赖自身的 State
+
+衍生状态只依赖当前 Model 的 State，State 会作为第一个参数，传入衍生状态的定义函数中。
+
+例如， todo 应用的 State 有 `items` 和 `filter`，`filter` 用于过滤当前页面显示的 todo 项，所以我们定义了一个 `visibleTodos` 的衍生状态可以直接在组件中使用。示例代码如下：
+
+```ts
+/**
+ *  假设 todo item 结构如下：
+{
+    id: string;          // id
+    text: string;        // todo 事项
+    completed: boolean;  // 完成状态：0 代表未完成，1 代表完成
+}
+**/
+
+const todoModel = model('todo').define({
+  state: {
+    items: [],
+    filter: 'ALL', // ALL: 显示全部；COMPLETED：显示完成的事项；ACTIVE：显示未完成的事项
+  },
+  computed: {
+    visibleTodos: state => {
+      switch (state.filter) {
+        case 'ALL':
+          return state.items;
+        case 'COMPLETED':
+          return todos.filter(t => t.completed);
+        case 'ACTIVE':
+          return todos.filter(t => !t.completed);
+        default:
+          return [];
+      }
+    },
+  },
+});
+```
+
+
+衍生状态最终会和 Model 的 State 进行合并，因此，可以通过 Model 的 State 对象访问到衍生状态，例如，`visibleTodos` 在组件内的使用方式如下：
+
+```ts
+function Todo() {
+  const [state, actions] = useModel(todoModel);
+
+  return (
+    <div>
+      <div>
+        {state.visibleTodos.map(item => (
+          <div key={item.id}>{item.text}</div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+## 依赖其他 Model 的 State
+
+除了依赖当前 Model 的 State，衍生状态还依赖其他 Model 的 State，这时候衍生状态的定义格式为：
+
+```ts
+[stateKey]: [...depModels, (selfState, ...depModels) => computedState]
+```
+
+下面的示例，演示了 `barModel` 的衍生状态 `combinedValue` 是如何依赖 `fooModel` 的 State 的。
+
+```ts
+const fooModel = model('foo').define({
+  state: {
+    value: 'foo',
+  },
+});
+
+const barModel = model('bar').define({
+  state: {
+    value: 'foo',
+  },
+  computed: {
+    combinedValue: [
+      fooModel,
+      (state, fooState) => state.value + fooState.value,
+    ],
+  },
+});
+```
+
+## 函数类型的衍生状态
+
+衍生状态还可以返回一个函数。这时候衍生状态的定义格式为：
+
+```ts
+[stateKey]: (state) => (...args) => computedState    // 只依赖自身的 state
+[stateKey]: [...depModels, (selfState, ...depModels) => (...args) => computedState]  // 依赖其他 Model 的 state
+```
+
+假设，todo 应用的 state 不存储 `filter` 状态，而是直接在组件中使用，那么 `visibleTodos` 可以是一个函数类型的值，这个函数在组件中使用的时候，接收 `filter` 参数。如下所示：
+
+```ts
+const todoModel = model('todo').define({
+  state: {
+    items: [],
+  },
+  computed: {
+    visibleTodos: state => filter => {
+      switch (filter) {
+        case 'ALL':
+          return state.items;
+        case 'COMPLETED':
+          return todos.filter(t => t.completed);
+        case 'ACTIVE':
+          return todos.filter(t => !t.completed);
+        default:
+          return [];
+      }
+    },
+  },
+});
+
+function Todo(props) {
+  // filter 状态通过 props 传入
+  const { filter } = props;
+  const [state, actions] = useModel(todoModel);
+
+  // 计算得到最终要显示的 todos
+  const todos = state.visibleTodos(filter);
+
+  return (
+    <div>
+      <div>
+        {todos.map(item => (
+          <div key={item.id}>{item.text}</div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+:::info 更多参考
+[使用 Model](/docs/guides/topic-detail/model/computed-state)
+:::

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

@@ -0,0 +1,66 @@
+---
+sidebar_position: 2
+title: 创建 Model
+---
+
+上一节的计数器应用中，我们简单演示了如何创建一个 Model。本节我们将详细介绍 Model 的创建方法。
+
+通过 `model` API 创建 Model，例如，`model('foo')` 表示要创建一个名为 `foo` 的 Model，通过调用 `model('foo')` 返回的 `define` 函数，定义 Model 包含的 State、Actions 等：
+
+``` js
+import { model, useModel } from '@modern-js/runtime/model';
+
+const fooModel = model('foo').define({
+  state: {
+    value: 'foo',
+  },
+  actions: {
+    setValue: (state, payload){
+      state.value = payload
+    }
+  }
+});
+```
+
+:::info 注
+- Model 中的 Action 中不能包含有副作用的逻辑，如请求 HTTP 接口，访问 localStorage 等。
+- `setValue` 内部直接修改了入参 State，看起来是违反了纯函数的定义，实际上 Reduck 内部使用 [immer](https://github.com/immerjs/immer) 来修改不可变对象，保证了这种写法不会影响对象的不可变性，所以 `setValue` 仍然是一个纯函数。当然，你也可以直接在 Action 中返回一个新对象，不过这样的写法会更加复杂一些。
+:::
+
+`define` 接收的参数，只是对 Model 原始结构的描述：内部定义的 State、Actions 等。`define` 返回值 `fooModel` 才是真正创建得到的 Model 对象。例如，虽然 `setValue`，有 2 个参数，但是当真正调用 `setValue` 这个 Action 时，我们只需要传入 `payload` 一个参数，因为我们调用的是 `fooModel` 上的 Action 方法，而不是 Model 原始结构上描述的 Action 方法。详细参考[使用 Model](/docs/guides/topic-detail/model/use-model)。
+
+`define` 除了接收对象类型的参数，还可以接收函数类型的参数。例如：
+
+``` js
+import { model, useModel } from '@modern-js/runtime/model';
+
+const fooModel = model('foo').define((context, utils) => {
+  return {
+    state: {
+      value: 'foo',
+    },
+    actions: {
+      setValue: (state, payload){
+        state.value = payload
+      }
+    }
+  }
+});
+```
+
+通过函数定义 Model 时，函数内部会自动传入 `context`、`utils` 2 个参数，`context` 是 Reduck 的上下文对象，可以获取到 `store` 对象，`utils` 提供了一组工具函数，方便实现 Model 通信等复杂功能需求。
+
+
+Model 支持复制。例如：
+
+``` ts
+const barModel = fooModel('bar');
+```
+
+barModel 是基于 fooModel 创建出一个的新的 Model 对象，类比面向对象编程语言中的概念，barModel 和 fooModel 是基于同一个类（Class）创建出的 2 个实例对象。当两个模块的状态管理逻辑相同，例如一个页面中的两个 tab 模块，使用的数据的结构和逻辑相同，区别只是从不同的接口获取数据，那么可以通过 Model 复制的方式，创建 2 个不同的 Model 对象。
+
+
+:::info 补充信息
+本节涉及的 API 的详细定义，请参考[这里](/docs/apis/app/runtime/model/model_)。
+:::
+

package/zh/guides/topic-detail/model/faq.md

@@ -0,0 +1,43 @@
+---
+sidebar_position: 13
+title: 常见问题
+---
+
+# 常见问题
+
+## 浏览器兼容性
+
+Reduck 的编译构建产物默认使用 ES6 语法，如果你需要支持更低版本的浏览器，请将 `@modern-js-reduck` 命名空间下的所有包加入到应用的编译过程。
+
+:::info 补充信息
+Reduck 使用的 [`@babel/preset-env`](https://babeljs.io/docs/en/babel-preset-env) 的详细[配置](https://github.com/modern-js-dev/reduck/blob/main/common/config.js#L10~L17)。
+:::
+
+## 微前端子应用 Model 访问主应用 Model
+
+微前端子应用 Model 访问主应用 Model 时，如果该 **Model** 在主应用尚未挂载，会自动挂载到子应用上。
+
+示例：
+
+```ts
+import { useModel } from '@modern-js/runtime/model';
+import parentModel from '@MasterApp/models/todoModel';
+
+function SubModelApp() {
+  const [state, actions] = useModel(parentModel);
+
+  return <div>...</div>
+}
+```
+
+![微前端通信流程图](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/mf-communicate.svg)
+
+为了避免意外降级挂载，建议将主应用所需要共享的 Model 预先挂载：
+
+```ts
+// App 是主应用的入口组件，sharedModel1、sharedModel2 是需要共享的 Model。
+App.models = [
+  sharedModel1,
+  sharedModel2
+]
+```