npm - @modern-js/main-doc - Versions diffs - 2.69.4 → 3.0.0-alpha.0 - Mend

@modern-js/main-doc 2.69.4 → 3.0.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (540) hide show

package/docs/zh/guides/topic-detail/micro-frontend/c02-development.mdx DELETED Viewed

@@ -1,332 +0,0 @@
----
-sidebar_position: 2
-title: 体验微前端
----
-# 体验微前端
-通过本章你可以了解到：
-- 如何创建微前端项目的主应用、子应用。
-- 微前端项目开发的基本流程。
-## 创建应用
-目前项目的路由模式分为以下三种
-- [约定式路由](/guides/concept/entries.html#约定式路由)
-- [自控式路由](/guides/concept/entries.html#自控式路由)
-- 其他 (项目自行安装和使用 `react-router-dom`)
-在本教程中我们会为主应用创建两个子应用 Table 和 Dashboard (Table 为约定式路由，Dashboard 为自控式路由)
-### 创建约定式路由主应用
-通过命令行工具初始化项目：
-```bash
-mkdir masterApp && cd masterApp
-npx @modern-js/create@latest
-```
-import DefaultMWAGenerate from '@site-docs/components/default-mwa-generate';
-<DefaultMWAGenerate />
-完成项目创建后我们可以通过 `pnpm run new` 来开启 `微前端` 功能：
-```bash
-? 请选择你想要的操作 启用可选功能
-? 请选择功能名称 启用「微前端」模式
-```
-接下来，让我们注册微前端插件并添加开启微前端主应用，并增加子应用列表：
-import EnableMicroFrontend from '@site-docs/components/enable-micro-frontend';
-<EnableMicroFrontend />
-然后我们在 routes 文件夹下新建两个目录
-- table (用于加载约定式路由子应用)
-- dashboard (用于加载自控式路由子应用)
-在这两个目录下我们需要新建一个 `$.tsx` 文件作为主应用约定式路由的入口($ 代表模糊匹配，即 `/table` 和 `/table/test` 都会匹配到这个 `$.tsx` 作为该路由的入口文件，这会保证在微前端场景下正确加载子应用路由)
-#### 加载约定式路由子应用
-```js title="src/routes/table/$.tsx"
-import { useModuleApps } from '@modern-js/plugin-garfish/runtime';
-const Index = () => {
-  const { Table } = useModuleApps();
-  return (
-    <div>
-      <Table />
-    </div>
-  );
-};
-export default Index;
-```
-#### 加载自控式路由子应用
-```js title="src/routes/dashboard/$.tsx"
-import { useModuleApps } from '@modern-js/plugin-garfish/runtime';
-const Index = () => {
-  const { Dashboard } = useModuleApps();
-  return (
-    <div>
-      <Dashboard />
-    </div>
-  );
-};
-export default Index;
-```
-#### 路由跳转
-此时主应用配置已经完成，通过路由即可加载子应用，修改主应用的 `layout.tsx` 来跳转路由
-```js title="src/route/layout.tsx"
-import { Outlet, Link } from '@modern-js/runtime/router';
-const Layout = () => (
-  <div>
-    <div>
-      <Link to={'/table'}>加载约定式路由子应用</Link>
-    </div>
-    <div>
-      <Link to={'/dashboard'}>加载自控式路由子应用</Link>
-    </div>
-    <div>
-      <Link to={'/'}>卸载子应用</Link>
-    </div>
-    <Outlet />
-  </div>
-);
-export default Layout;
-```
-### 创建自控式路由主应用
-通过命令行工具初始化项目：
-```bash
-mkdir masterApp && cd masterApp
-npx @modern-js/create@latest
-```
-<DefaultMWAGenerate />
-完成项目创建后我们可以通过 `pnpm run new` 来开启 `微前端` 功能：
-```bash
-? 请选择你想要的操作 启用可选功能
-? 请选择功能名称 启用「微前端」模式
-```
-接下来，让我们注册微前端插件并添加开启微前端主应用，并增加子应用列表：
-<EnableMicroFrontend />
-由于是自控式路由，我们删除掉 `routes` 文件夹并在 `src` 目录下增加 `App.tsx` 文件，此处如果使用的 `非 MApp` 组件，需要通过 `React Router v6` 的 `createBrowserRouter` API 来创建路由
-#### 加载子应用
-import CustomRouterMicroFrontend from '@site-docs/components/custom-router-micro-frontend';
-<CustomRouterMicroFrontend />
-### 创建其他主应用
-项目内自己安装和使用 `react-router-dom` , 与自控式路由唯一的区别是, 设置 `router: false` 后 plugin-garfish 无法获得 `useLocation` `useHref` 等 hook 来辅助计算 basename 和主子应用路由同步
-import { Tab, Tabs } from 'rspress/theme';
-<Tabs>
-<Tab label="react-router-dom@6">
-```tsx
-import { useLocation, useHref } from 'react-router-dom';
-const App = () => {
-  const basename = useHref('/table');
-  const { Table } = useModuleApps();
-  return <Table useLocation={useLocation} basename={basename} />;
-};
-```
-</Tab>
-<Tab label="react-router-dom@5">
-```tsx
-import { useLocation, useHistory } from 'react-router-dom';
-const App = () => {
-  const history = useHistory();
-  const basename = history.createHref({ pathname: '/table' });
-  const { Table } = useModuleApps();
-  return <Table useLocation={useLocation} basename={basename} />;
-};
-```
-</Tab>
-</Tabs>
-### 创建约定式路由子应用
-通过命令行工具初始化项目：
-```bash
-mkdir table && cd table
-npx @modern-js/create@latest
-```
-按照如下选择，生成项目：
-<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({
-  dev: {
-    port: 8081,
-  },
-  runtime: {
-    router: true,
-  },
-  deploy: {
-    microFrontend: true,
-  },
-  plugins: [appTools(), garfishPlugin()],
-});
-```
-添加 `src/routes/page.tsx` 代码
-```js title="src/routes/page.tsx"
-const Index = () => {
-  return (
-    <div className="container-box">subApp: 约定式路由的子应用的根路由</div>
-  );
-};
-export default Index;
-```
-### 创建自控式路由子应用
-通过命令行工具初始化项目：
-```bash
-mkdir dashboard && cd dashboard
-npx @modern-js/create@latest
-```
-按照如下选择，生成项目：
-<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({
-  dev: {
-    port: 8082,
-  },
-  runtime: {
-    router: true,
-  },
-  deploy: {
-    microFrontend: true,
-  },
-  plugins: [appTools(), garfishPlugin()],
-});
-```
-自控式路由需要删除掉 `routes` 文件夹并在 `src` 目录下新建 `App.tsx`
-并在 `src/App.tsx` 添加代码，注意需要从 `props` 中解析并传递 `basename` 给 `BrowserRouter`
-```js title="src/App.tsx"
-import { BrowserRouter, Route, Routes } from '@modern-js/runtime/router';
-export default (props: { basename: string }) => {
-  const { basename } = props;
-  return (
-    <BrowserRouter basename={basename}>
-      <Routes>
-        <Route index element={<div>自控式路由子应用根路由</div>} />
-        <Route path={'path'} element={<div>自控式路由子应用子路由</div>} />
-      </Routes>
-    </BrowserRouter>
-  );
-};
-```
-## 调试
-按顺序在目录执行 `pnpm run dev` 命令启动应用：
-- masterApp 主应用 `http://localhost:8080`
-- table 子应用(约定式路由) `http://localhost:8081`
-- dashboard 子应用(自控式路由) `http://localhost:8082`
-访问主应用地址 `http://localhost:8080`
-在完成了微前端整体开发流程的体验后，你可以进一步了解如何 [开发主应用](/guides/topic-detail/micro-frontend/c03-main-app)
-## Modern.js 微前端和直接使用 Garfish 的区别
-使用纯 `Garfish` API 开发微前端应用时
-- 主应用：
-  - 安装 Garfish 依赖并使用 `Garfish.run` 注册子应用 [参考](https://www.garfishjs.org/api/run.html)
-  - 提供一个常驻的 `DOM` 节点供子应用挂载 [参考](https://www.garfishjs.org/api/registerApp.html)
-- 子应用：
-  - 导出 `provider` [参考](https://www.garfishjs.org/guide/quick-start/start.html#2%E5%AF%BC%E5%87%BA-provider-%E5%87%BD%E6%95%B0)
-  - 设置应用的 `basename` [参考](https://www.garfishjs.org/guide/quick-start/start.html#3-%E8%AE%BE%E7%BD%AE%E5%BA%94%E7%94%A8%E8%B7%AF%E7%94%B1-basename)
-区别于直接使用 `Garfish` 运行时 API 开发微前端项目，`Modern.js` 的微前端方案更加开箱即用。
-使用 `pnpm new` 启用微前端模式后会自动在 `Modern.js` 应用中集成 `Garfish` 插件，在 `Garfish`
-插件的加持下，你只需要
-- 主应用：
-  - 配置 `runtime.masterApp.apps` 参数注册子应用
-  - 使用 `useModuleApps` API 获取子应用实例并在组件中完成渲染
-- 子应用：
-  - 配置 `deploy.microFrontend`
-所以插件中为你做了如下事情
-- 帮助你通过 `Garfish` 运行时 API 自动注册子应用（主应用）
-- `useModulesApps` 函数的返回值提供了一个常驻的 `DOM` 节点供子应用挂载（主应用）
-- 帮助你正确导出了 `provider`（子应用）
-- 帮助你正确设置了 `basename` 给 `Modern.js` 运行时提供 `Router` 实例，如果是`自控式路由`或`手动引入的 react-router-dom` 那么需要从 `App.tsx` 的 `props` 中获取 `basename` 手动传递给引入的 `Router 实例`（子应用）
-## 常见问题
-自查手册: https://www.garfishjs.org/issues/

package/docs/zh/guides/topic-detail/micro-frontend/c03-main-app.mdx DELETED Viewed

@@ -1,296 +0,0 @@
----
-sidebar_position: 3
-title: 开发主应用
----
-# 开发主应用
-在上一章 [体验微前端](/guides/topic-detail/micro-frontend/c02-development) 通过一个示例演示了如何创建和配置微前端子应用，通过本章你可以进一步了解如何开发主应用，以及它的常见配置。
-在通过 `@modern-js/create` 命令创建 Modern.js 工程后，可以在项目中执行 `pnpm run new`（实际执行了 `modern new` 命令），在选择了「微前端」模式后，会安装微前端依赖依赖，只需手动注册插件即可。
-import EnableMicroFrontend from '@site-docs/components/enable-micro-frontend';
-<EnableMicroFrontend />
-## 注册子应用信息
-当在 `masterApp` 配置上提供了信息后，将会认为该应用为主应用，目前存在两种子应用信息的配置方式，这两种方式分别应用于不同的场景。
-### 直接注册子应用信息
-可以直接通过配置注册子应用信息：
-:::tip 提示
-可以通过 API [defineConfig](/apis/app/runtime/app/define-config) 在运行时进行配置。
-当参数为函数时无法被序列化到产物代码，所以在涉及到函数之类的配置时请通过 defineConfig 来进行配置
-:::
-import MicroRuntimeConfig from '@site-docs/components/micro-runtime-config';
-<MicroRuntimeConfig />
-### 自定义远程应用列表
-通过该函数可以拉取远程的子应用列表，并将其注册至运行时框架：
-```ts title="src/modern.runtime.ts"
-import { defineRuntimeConfig } from '@modern-js/runtime';
-export default defineRuntimeConfig({
-  masterApp: {
-    manifest: {
-      getAppList: async () => {
-        // 可以从其他远程接口获取
-        return [
-          {
-            name: 'Table',
-            entry: 'http://localhost:8081',
-            // activeWhen: '/table'
-          },
-          {
-            name: 'Dashboard',
-            entry: 'http://localhost:8082',
-            // activeWhen: '/dashboard'
-          },
-        ];
-      },
-    },
-  },
-});
-```
-## 渲染子应用
-在微前端中分为两种加载子应用的方式：
-1. **子应用组件** 获取到每个子应用的组件，之后就可以像使用普通的 `React` 组件一样渲染微前端的子应用。
-2. **集中式路由** 通过集中式的路由配置，自动根据当前页面 `pathname` 激活渲染对应的子应用。
-### 子应用组件
-开发者使用 `useModuleApps` 方法可以获取到各个子应用的组件。
-再通过 `router` 组件的结合运用，开发者可以自控式的根据不同的路由渲染不同的子应用。
-假设我们的子应用列表配置如下：
-<EnableMicroFrontend />
-编辑主应用 `App.tsx` 文件如下：
-```js title="App.tsx"
-import { useModuleApps } from '@modern-js/plugin-garfish/runtime';
-import {
-  RouterProvider,
-  Route,
-  createBrowserRouter,
-  createRoutesFromElements,
-  BrowserRouter,
-  Link,
-  Outlet,
-} from '@modern-js/runtime/router';
-const AppLayout = () => (
-  <>
-    <div>
-      <Link to={'/table'}>加载约定式路由子应用</Link>
-    </div>
-    <div>
-      <Link to={'/dashboard'}>加载自控式路由子应用</Link>
-    </div>
-    <div>
-      <Link to={'/'}>卸载子应用</Link>
-    </div>
-    <Outlet />
-  </>
-);
-export default () => {
-  const { apps, MApp } = useModuleApps();
-  // 使用的不是 MApp 组件，需要使用 createBrowserRouter 来创建路由
-  const router = createBrowserRouter(
-    createRoutesFromElements(
-      <Route path="/" element={<AppLayout />}>
-        {apps.map(app => {
-          const { Component } = app;
-          // 模糊匹配，path 需要写成类似 abc/* 的模式
-          return (
-            <Route
-              key={app.name}
-              path={`${app.name.toLowerCase()}/*`}
-              element={
-                <Component
-                  loadable={{
-                    loading: ({ pastDelay, error }: any) => {
-                      if (error) {
-                        return <div>error: {error?.message}</div>;
-                      } else if (pastDelay) {
-                        return <div>loading</div>;
-                      } else {
-                        return null;
-                      }
-                    },
-                  }}
-                />
-              }
-            />
-          );
-        })}
-      </Route>,
-    ),
-  );
-  return (
-    // 方法一：使用 MApp 自动根据配置的 activeWhen 参数加载子应用(本项目配置在 modern.config.ts 中)
-    // <BrowserRouter>
-    //   <MApp />
-    // </BrowserRouter>
-    // 方法二：手动写 Route 组件方式加载子应用，方便于需要鉴权等需要前置操作的场景
-    <>
-      <RouterProvider router={router} />
-    </>
-  );
-};
-```
-这里通过 `Route` 组件自定义了 **Table** 的激活路由为 **/table**， **Dashboard** 的激活路由为 **/dashboard**。
-### 集中式路由
-**集中式路由** 是将子应用的激活路由集中配置的方式。我们给子应用列表信息添加 `activeWhen` 字段来启用 **集中式路由**。
-<MicroRuntimeConfig />
-然后在主应用中使用 `useModuleApp` 方法获取 `MApp` 组件, 并在主应用渲染 `MApp`。
-```tsx title=主应用：App.tsx
-import { useModuleApp } from '@modern-js/plugin-garfish/runtime';
-function App() {
-  const { MApp } = useModuleApps();
-  return (
-    <div>
-      <MApp />
-    </div>
-  );
-}
-```
-这样启动应用后，访问 `/table` 路由，会渲染 `Table` 子应用，访问 `/dashboard` 路由，会渲染 `Dashboard` 子应用。
-### 两种模式混用
-当然 **子应用组件** 和 **集中式路由** 是可以混合使用的。
-- 一部分子应用作为 **子应用组件** 激活，另外一部分作为 **集中式路由** 激活。
-- 一部分子应用既可以作为 **集中式路由** 激活，也可以作为 **子应用组件** 激活。
-### 添加 loading
-通过配置 `loadable` 配置，可以为「集中式路由」、「子应用」添加 loading 组件，并可以考虑错误、超时、闪烁等情况的出现，从而为用户提供更好的用户体验。该功能的设计与实现参考至 [react-loadable](https://github.com/jamiebuilds/react-loadable)，基本功能较为相似。
-```tsx
-function Loading() {
-  return <div>Loading...</div>;
-}
-function App(){
-  return <>
-    <Table
-      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 <>
-    <Table
-      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 <>
-    <Table
-      loadable={{
-        loading: Loading,
-        timeOut: 10000 // 10s
-      }}
-    />
-  <>
-}
-```

package/docs/zh/guides/topic-detail/micro-frontend/c04-communicate.mdx DELETED Viewed

@@ -1,58 +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/docs/zh/guides/topic-detail/micro-frontend/c05-mixed-stack.mdx DELETED Viewed

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