@modern-js/main-doc 2.3.0 → 2.4.0

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

@@ -10,19 +10,20 @@ title: 体验微前端
 - 微前端项目开发的基本流程。
 
 ## 创建应用
+目前支持两种路由模式
+- 自控式路由
+- 约定式路由
 
-在这次的实践中，我们需要创建三个应用，分别为 1 个主应用，2 个子应用：
+首先明确主应用的路由模式 [创建约定式路由主应用](#创建约定式路由主应用) 或 [创建自控式路由主应用](#创建自控式路由主应用)
 
-- main 主应用
-- dashboard 子应用
-- table 子应用
+在本次体验中我们会为主应用创建两个子应用 Table 和 Dashboard (Table 为约定式路由，Dashboard 为自控式路由)
 
-### 创建 main 主应用
+### 创建约定式路由主应用
 
 通过命令行工具初始化项目：
 
 ```bash
-mkdir main && cd main
+mkdir masterApp && cd masterApp
 npx @modern-js/create
 ```
 
@@ -43,16 +44,96 @@ import EnableMicroFrontend from "@site-docs/components/enable-micro-frontend";
 
 <EnableMicroFrontend />
 
-import MicroRuntimeConfig from "@site-docs/components/micro-runtime-config";
+然后我们在 routes 文件夹下新建两个目录
+- table (用于加载约定式路由子应用)
+- dashboard (用于加载自控式路由子应用)
 
-<MicroRuntimeConfig />
+在这两个目录下我们需要新建一个 `$.tsx` 文件作为主应用约定式路由的入口($ 代表模糊匹配，即 `/table` 和 `/table/test` 都会匹配到这个 `$.tsx` 作为该路由的入口文件，这会保证在微前端场景下正确加载子应用路由)
 
-### 创建 dashboard 子应用
+#### 加载约定式路由子应用
+```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 dashboard && cd dashboard
+mkdir masterApp && cd masterApp
+npx @modern-js/create
+```
+
+<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 />
+
+### 创建约定式路由子应用
+
+通过命令行工具初始化项目：
+
+```bash
+mkdir table && cd table
 npx @modern-js/create
 ```
 
@@ -74,6 +155,9 @@ import appTools, { defineConfig } from '@modern-js/app-tools';
 import garfishPlugin from '@modern-js/plugin-garfish';
 
 export default defineConfig({
+  dev: {
+    port: 8081
+  },
   runtime: {
     router: true,
     state: true,
@@ -85,12 +169,23 @@ export default defineConfig({
 });
 ```
 
-### 创建 table 子应用
+添加 `src/routes/page.tsx` 代码
+```js title="src/routes/page.tsx"
+const Index = () => {
+  return (
+    <div className="container-box">subApp: 约定式路由的子应用的根路由</div>
+  )
+}
+
+export default Index;
+```
+
+### 创建自控式路由子应用
 
 通过命令行工具初始化项目：
 
 ```bash
-mkdir table && cd table
+mkdir dashboard && cd dashboard
 npx @modern-js/create
 ```
 
@@ -112,6 +207,9 @@ import appTools, { defineConfig } from '@modern-js/app-tools';
 import garfishPlugin from '@modern-js/plugin-garfish';
 
 export default defineConfig({
+  dev: {
+    port: 8082
+  },
   runtime: {
     router: true,
     state: true,
@@ -122,67 +220,36 @@ export default defineConfig({
   plugins: [appTools(), garfishPlugin()],
 });
 ```
+自控式路由需要删除掉 `routes` 文件夹并在 `src` 目录下新建 `App.tsx`
 
-## 添加代码
+并在 `src/App.tsx` 添加代码，注意需要从 `props` 中解析并传递 `basename` 给 `BrowserRouter`
 
-### main 主应用
+```js title="src/App.tsx"
+import { BrowserRouter, Route, Routes } from '@modern-js/runtime/router';
 
-删除 `src/routers` 目录, 创建 `src/App.tsx`，并添加如下内容：
+export default (props: {basename: string}) => {
+  const { basename } = props;
 
-```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>
+    <BrowserRouter basename={basename}>
+      <Routes>
+        <Route index element={<div>自控式路由子应用根路由</div>} />
+        <Route path={'path'} element={<div>自控式路由子应用子路由</div>} />
+      </Routes>
+    </BrowserRouter>
   );
 };
-
-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>;
 ```
 
 ## 调试
+按顺序在目录执行 `pnpm run dev` 命令启动应用：
+- masterApp 主应用 `http://localhost:8080`
+- table 子应用(约定式路由) `http://localhost:8081`
+- dashboard 子应用(自控式路由) `http://localhost:8082`
 
-按顺序在 `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)
+访问主应用地址 `http://localhost:8080`
 
-在完成了微前端整体开发流程的体验后，你可以进一步了解如何 [开发主应用](./c03-main-app.md)
+在完成了微前端整体开发流程的体验后，你可以进一步了解如何 [开发主应用](/guides/topic-detail/micro-frontend/c03-main-app)
 
 ## 常见问题
 

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

@@ -4,7 +4,7 @@ title: 开发主应用
 ---
 # 开发主应用
 
-在上一章 [体验微前端](./c02-development.md) 通过一个示例演示了如何创建和配置微前端子应用，通过本章你可以进一步了解如何开发主应用，以及它的常见配置。
+在上一章 [体验微前端](/guides/topic-detail/micro-frontend/c02-development.md) 通过一个示例演示了如何创建和配置微前端子应用，通过本章你可以进一步了解如何开发主应用，以及它的常见配置。
 
 在通过 `@modern-js/create` 命令创建应用工程后，可以在项目中执行 `pnpm run new`（实际执行了 `modern new` 命令），在选择了「微前端」模式后，会安装微前端依赖依赖，只需手动注册插件即可。
 
@@ -40,16 +40,15 @@ defineConfig(App, {
     manifest: {
       getAppList: async () => {
         // 可以从其他远程接口获取
-        return [
-          {
-            name: 'DashBoard',
-            entry: 'http://127.0.0.1:8081/',
-          },
-          {
-            name: 'TableList',
-            entry: 'http://localhost:8082',
-          },
-        ];
+        return [{
+          name: 'SubConvention',
+          entry: 'http://localhost:3002',
+          // activeWhen: '/SubConvention'
+        }, {
+          name: 'SubCustom',
+          entry: 'http://localhost:3003'
+          // activeWhen: '/SubConvention'
+        }];
       },
     },
   },
@@ -75,39 +74,71 @@ defineConfig(App, {
 
 编辑主应用 `App.tsx` 文件如下：
 
-```tsx title=主应用：App.tsx
+```js 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();
+import { RouterProvider, Route, createBrowserRouter, createRoutesFromElements, BrowserRouter, Link, Outlet } from '@modern-js/runtime/router';
 
-  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;
+const AppLayout = () => (
+  <>
+    <div><Link to={'/SubConvention'}>加载约定式路由子应用</Link></div>
+    <div><Link to={'/SubCustom'}>加载自控式路由子应用</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}/*`}
+              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>
-      <Route path="/table">
-        <TableList />
+            />
+          )
+        })}
       </Route>
-    </div>
+    )
   );
-}
+
+  return (
+    // 方法一：使用 MApp 自动根据配置的 activeWhen 参数加载子应用(本项目配置在 modern.config.ts 中)
+    // <BrowserRouter>
+    //   <MApp />
+    // </BrowserRouter>
+
+    // 方法二：手动写 Route 组件方式加载子应用，方便于需要鉴权等需要前置操作的场景
+    <>
+      <RouterProvider router={router} />
+    </>
+  );
+};
 ```
 
-这里通过 `Route` 组件自定义了 **DashBoard** 的激活路由为 **/dashboard**， **TableList** 的激活路由为 **/table**。
+这里通过 `Route` 组件自定义了 **SubConvention** 的激活路由为 **/SubConvention**， **SubCustom** 的激活路由为 **/SubCustom**。
 
 ### 集中式路由
 
@@ -131,7 +162,7 @@ function App() {
 }
 ```
 
-这样启动应用后，访问 `/dashboard` 路由，会渲染 `Dashboard` 子应用，访问 `/table` 路由，会渲染 `TableList` 子应用。
+这样启动应用后，访问 `/SubCustom` 路由，会渲染 `SubCustom` 子应用，访问 `/SubConvention` 路由，会渲染 `SubConvention` 子应用。
 
 ### 两种模式混用
 
@@ -151,7 +182,7 @@ function Loading() {
 
 function App(){
   return <>
-    <DashBoard
+    <SubCustom
       loadable={{
         loading: Loading,
       }}
@@ -198,7 +229,7 @@ function Loading({ error, pastDelay }) {
 
 function App(){
   return <>
-    <DashBoard
+    <SubCustom
       loadable={{
         loading: Loading,
         delay: 300 // 0.3 seconds
@@ -234,7 +265,7 @@ function Loading({ error, timeOut, pastDelay }) {
 
 function App(){
   return <>
-    <DashBoard
+    <SubCustom
       loadable={{
         loading: Loading,
         timeOut: 10000 // 10s