@modern-js/main-doc 2.1.0 → 2.3.0

package/zh/guides/topic-detail/generator/project.md

@@ -1,117 +0,0 @@
----
-sidebar_position: 2
----
-
-# 项目生成器
-
-Modern.js 提供了 `@modern-js/create` 作为项目生成器用于进行 Modern.js 工程方案项目创建。
-
-## 使用
-
-不需要全局安装 `@modern-js/create`，直接使用 npx 执行该工具即可：
-
-```bash
-npx @modern-js/create [projectDir]
-```
-
-:::info
-使用 npx 可以每次获取最新版本的 `@modern-js/create`。
-:::
-
-## 参数
-
-### [projectDir]
-
-项目目录名称。
-
-执行上述命令时，默认会在当前目录创建 `projectDir` 文件夹，并在该文件夹下初始化项目。该参数为空时，将会在当前目录直接生成初始化项目。
-
-### --version
-
-获取 `@modern-js/create` 工具版本。
-
-```bash
-$ npx @modern-js/create --version
-
-[INFO] @modern-js/create v2.0.0
-```
-
-### --lang
-
-指定执行语言，支持 `zh` 和 `en`。
-
-默认情况下，`@modern-js/create` 会自动识别用户的系统语言，选择使用中文或者英文，如果识别失败或者想手动指定语言，可以使用该参数。
-
-### -c, --config
-
-指定项目默认配置。
-
-默认情况下，`@modern-js/create` 在执行过程中会出现选择语言、包管理工具等交互问题，当需要提前指定这些配置内容时，可以通过该字段传入。
-
-该字段为 JSON 字符串，例如需执行包管理工具时：
-
-```bash
-npx @modern-js/create --config '{"packageManager": "pnpm"}'
-```
-
-具体配置信息可查看[工程方案配置](/docs/guides/topic-detail/generator/config/common)。
-
-### --no-need-install
-
-默认情况下，`@modern-js/create` 在创建项目完成后会自动安装依赖，使用该参数可以忽略安装依赖步骤。
-
-### --dist-tag <distTag\>
-
-指定生成器及 Modern.js 相关依赖版本。
-
-`@modern-js/create` 执行过程中会执行更小的微生成器，使用该参数可以执行执行的微生成器的版本号和对应的安装 Modern.js 相关依赖的版本号。
-
-### --registry <registry/>
-
-执行获取生成器及 npm 包的 npm registry。
-
-### --debug
-
-显示生成器执行过程中的调试日志信息。
-
-### --mwa
-
-一键创建应用工程方案项目。
-
-使用该参数后，`@modern-js/create` 将会使用配置默认值创建应用项目。
-
-### --module
-
-一键创建模块工程方案项目。
-
-使用该参数后，`@modern-js/create` 将会使用配置默认值创建模块项目。
-
-### --monorepo
-
-一键创建 Monorepo 工程方案项目。
-
-使用该参数后，`@modern-js/create` 将会使用配置默认值创建 Monorepo 项目。
-
-### --plugin <plugin\>
-
-指定生成器插件。
-
-Modern.js 支持使用生成器插件定制 Modern.js 默认的工程方案类型或者添加工程方案类型场景，该参数用户指定定制的生成器插件。
-
-关于定制生成器插件可以参考[开发生成器插件](/docs/guides/topic-detail/generator/plugin/abstract)。
-
-### --generator <generator\>
-
-指定微生成器。
-
-默认情况下 `@modern-js/create` 会执行 Modern.js 框架内置的微生成器，如果你需要执行定制的微生成器，又需要使用 `npx @modern-js/create` 的姿势，可直接使用该参数。
-
-关于定制微生成器可以参考[开发微生成器](/docs/guides/topic-detail/generator/codesmith/introduce)。
-
-### --packages <packages\>
-
-创建项目是指定特定包版本依赖。
-
-在创建项目时如果有需要指定特定包版本，可以使用该参数。该参数会在项目根目录的 `package.json` 中配置 `pnpm.overrides`(包管理工具选择 pnpm) 或者 `resolutions` 锁定包版本号。
-
-该参数值为 JSON 字符串。

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

@@ -1,28 +0,0 @@
----
-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

@@ -1,188 +0,0 @@
----
-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`：
-
-```js title="modern.config.ts"
-import appTools, { 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: [appTools(), garfishPlugin()],
-});
-```
-
-### 创建 table 子应用
-
-通过命令行工具初始化项目：
-
-```bash
-mkdir table && cd table
-npx @modern-js/create
-```
-
-按照如下选择，生成项目：
-
-<DefaultMWAGenerate/>
-
-我们执行 `pnpm run new` 来开启 `微前端`：
-
-```bash
-? 请选择你想要的操作 启用可选功能
-? 启用可选功能 启用「微前端」模式
-```
-
-接下来，让我们注册微前端插件并修改 `modern.config.ts`，添加微前端子应用的配置 `deploy.microFrontend`：
-
-```js title="modern.config.ts"
-import appTools, { 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: [appTools(), 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/zh/guides/topic-detail/micro-frontend/c03-main-app.md

@@ -1,243 +0,0 @@
----
-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/zh/guides/topic-detail/micro-frontend/c04-communicate.md

@@ -1,56 +0,0 @@
----
-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/c05-mixed-stack.md

@@ -1,24 +0,0 @@
----
-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) 开发即可。