@modern-js/main-doc 2.4.0 → 2.5.0

package/en/guides/concept/entries.mdx

@@ -1,7 +1,7 @@
 ---
-title: Entries
-sidebar_position: 2
+sidebar_position: 1
 ---
+
 # Entries
 
 Entries are Modern.js default file convention, and each entry in the project is a separate page, corresponding to a server level route.
@@ -15,11 +15,11 @@ Modern.js initialization project is a single entry, the project structure is as
 ```
 .
 ├── src
-│   ├── modern-app-env.d.ts
-│   └── routes
-│       ├── index.css
-│       ├── layout.tsx
-│       └── page.tsx
+│   ├── modern-app-env.d.ts
+│   └── routes
+│       ├── index.css
+│       ├── layout.tsx
+│       └── page.tsx
 ├── package.json
 ├── modern.config.ts
 ├── pnpm-lock.yaml
@@ -41,10 +41,10 @@ After execution, the `src/` directory will become the following structure:
 .
 ├── modern-app-env.d.ts
 ├── myapp
-│   └── routes
-│       ├── index.css
-│       ├── layout.tsx
-│       └── page.tsx
+│   └── routes
+│       ├── index.css
+│       ├── layout.tsx
+│       └── page.tsx
 └── new-entry
     └── routes
         ├── index.css

package/en/guides/css/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "CSS Solutions",
+  "position": 4,
+  "collapsed": false
+}

package/en/guides/{basic-features/css → css}/less-sass.mdx

@@ -12,6 +12,6 @@ sidebar_position: 4
 - If you need to customize the configuration of [sass-loader](https://github.com/webpack-contrib/sass-loader), please refer to the [tools.less](/configure/app/tools/sass).
 
 :::tip
-CSS files pre-compiled by Less and Sass will still undergo Modern.js build-in [PostCSS](https://postcss.org/) conversion, which has good browser compatibility. For related content, please refer to [[PostCSS](/guides/basic-features/css/postcss)].
+CSS files pre-compiled by Less and Sass will still undergo Modern.js build-in [PostCSS](https://postcss.org/) conversion, which has good browser compatibility. For related content, please refer to [[PostCSS](/guides/css/postcss)].
 
 :::

package/en/guides/get-started/introduction.mdx

@@ -0,0 +1,34 @@
+---
+title: Introduction
+sidebar_position: 1
+---
+# Introduction
+
+## Modern.js Introduction
+
+**Modern.js** is a progressive modern web development framework based on React.
+
+The framework has a variety of built-in out-of-the-box tools, excellent build performance, zero-configuration rendering paradigm switching, and integrated API calls. Starting from three solutions (Application solutions, Module solutions, Monorepo solutions), it supports front-end research and development of a complete period.
+
+Modern.js is ByteDance's underlying front-end framework, which has directly or indirectly served thousands of applications, including middle and back-end, PC Web, H5 and other application scenarios. The framework covers a full life cycle, has a complete plugin system, and provides a high degree of customization capabilities. Support custom solutions exclusive to business lines through generator plugin, customize various functional extensions and business requirements, and help developers build applications faster.
+
+## Why Modern.js
+
+Modern.js can provide developers with the ultimate **Development Experience**，make the app better **User Experience**.
+
+In the process of developing React applications, developers often need to design implementations for certain functions, or use other libraries and frameworks to solve these problems.
+
+Modern.js support all the configuration and tools required by React applications, and have built-in **additional functions and optimizations**. Developers can use React to build the UI of the application, and then gradually adopt Modern.js functions to solve common application requirements, such as routing, data fetch, state management, etc.
+
+It mainly contains the following features:
+
+- 🪜 **Progressive**：Create projects with the most streamlined templates, gradually turn on plugin capabilities through generators, and customize solutions.
+- 🏠 **Integration**：The development is unique to the production environment Web Server, CSR and SSR are isomorphic development, and the function as the API service call.
+- 📦 **Out Of The Box**：Default TS support, built-in build core, ESLint, debugging tools, full functionality can be tested.
+- 🌏 **Ecology**：Self-developed state management, micro frontend, module packaging, Monorepo solution and other peripheral requirements.
+- 🕸 **Routing Modes**：Contains controlled routing, routing based on file conventions (nested routing), configurable routing, etc.
+- 🚀 **Independently Build Core**：Support a variety of packaging tools, deep optimization bundle.
+
+## Next
+
+If you want to know how to use Modern.js, you can try [Create your first app](/tutorials/first-app/c01-start), or read [Quick Start](/guides/get-started/quick-start).

package/en/guides/get-started/quick-start.mdx

@@ -1,7 +1,8 @@
 ---
 title: Quick Start
-sidebar_position: 1
+sidebar_position: 2
 ---
+
 # Quick Start
 
 ## Environment
@@ -81,7 +82,6 @@ Features can be enabled through the configuration file, or the default behavior
 ```ts
 import { defineConfig } from '@modern-js/app-tools';
 
-// https://modernjs.dev/docs/apis/app/config
 export default defineConfig({
   runtime: {
     router: true,

package/en/guides/get-started/upgrade.mdx

@@ -1,7 +1,8 @@
 ---
 title: Upgrade
-sidebar_position: 2
+sidebar_position: 3
 ---
+
 # Upgrade
 
 ## Upgrade with command

package/en/guides/topic-detail/_category_.json

@@ -1,5 +1,5 @@
 {
   "label": "Topic Detail",
-  "position": 5,
-  "collapsed": true
+  "position": 6,
+  "collapsed": false
 }

package/en/guides/topic-detail/framework-plugin/hook.mdx

@@ -76,7 +76,7 @@ pipeline.run(5); // 6
 
 上面的例子就是以 Pipeline 为例描述的，这里就不赘述了，在 Pipeline 这个大类中，提供了两个小类：Sync 和 Async，顾名思义，它们的区别就是管理的函数的类型是 Sync 的还是 Async 的。
 
-:::info 注
+:::info
 当 Pipeline 中没有函数或者所有函数都调用了 `next` 函数，则就需要在运行的时候提供：
 
 ```ts

package/en/guides/topic-detail/generator/plugin/api/hook/onForged.mdx

@@ -28,7 +28,7 @@ The onForged parameter is a callback function, and the function parameters are `
 
 ### api
 
-A list of supported functions in `onForged` time to live, specifically viewable [File API] (/docs/guides/topic-detail/generator/plugin/api/file/introduce) and [Enable function API] (/docs/guides/topic-detail/generator/plugin/api/new/introduce).
+A list of supported functions in `onForged` time to live, specifically viewable [File API](/guides/topic-detail/generator/plugin/api/file/introduce) and [Enable function API](/guides/topic-detail/generator/plugin/api/new/introduce).
 
 ### inputData
 

package/en/guides/topic-detail/generator/plugin/develop.mdx

@@ -122,4 +122,4 @@ The `api` will provide some npm, Git and other methods, which can install depend
 
 `input` is the current user input, which can be used to obtain the current input information and configuration information of the user.
 
-The API functions supported in `afterForged` can also be found in [Generator Plugin API] (/docs/guides/topic-detail/generator/plugin/api/hook/afterForged).
+The API functions supported in `afterForged` can also be found in [Generator Plugin API](/guides/topic-detail/generator/plugin/api/hook/afterForged).

package/en/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/en/guides/topic-detail/micro-frontend/c03-main-app.mdx

@@ -4,7 +4,7 @@ title: 开发主应用
 ---
 # 开发主应用
 
-在上一章 [体验微前端](./c02-development.md) 通过一个示例演示了如何创建和配置微前端子应用，通过本章你可以进一步了解如何开发主应用，以及它的常见配置。
+在上一章 [体验微前端](/guides/topic-detail/micro-frontend/c02-development) 通过一个示例演示了如何创建和配置微前端子应用，通过本章你可以进一步了解如何开发主应用，以及它的常见配置。
 
 在通过 `@modern-js/create` 命令创建应用工程后，可以在项目中执行 `pnpm run new`（实际执行了 `modern new` 命令），在选择了「微前端」模式后，会安装微前端依赖依赖，只需手动注册插件即可。
 
@@ -20,7 +20,7 @@ import EnableMicroFrontend from "@site-docs/components/enable-micro-frontend";
 
 可以直接通过配置注册子应用信息：
 
-:::tip 提示
+:::tip
 可以通过 API [defineConfig](/apis/app/runtime/app/define-config) 在运行时进行配置。
 当参数为函数时无法被序列化到产物代码，所以在涉及到函数之类的配置时请通过 defineConfig 来进行配置
 
@@ -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: 'Table',
+          entry: 'http://localhost:8001',
+          // activeWhen: '/table'
+        }, {
+          name: 'Dashboard',
+          entry: 'http://localhost:8002'
+          // activeWhen: '/dashboard'
+        }];
       },
     },
   },
@@ -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={'/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>
-      <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` 组件自定义了 **Table** 的激活路由为 **/table**， **Dashboard** 的激活路由为 **/dashboard**。
 
 ### 集中式路由
 
@@ -131,7 +162,7 @@ function App() {
 }
 ```
 
-这样启动应用后，访问 `/dashboard` 路由，会渲染 `Dashboard` 子应用，访问 `/table` 路由，会渲染 `TableList` 子应用。
+这样启动应用后，访问 `/table` 路由，会渲染 `Table` 子应用，访问 `/dashboard` 路由，会渲染 `Dashboard` 子应用。
 
 ### 两种模式混用
 
@@ -151,7 +182,7 @@ function Loading() {
 
 function App(){
   return <>
-    <DashBoard
+    <Table
       loadable={{
         loading: Loading,
       }}
@@ -198,7 +229,7 @@ function Loading({ error, pastDelay }) {
 
 function App(){
   return <>
-    <DashBoard
+    <Table
       loadable={{
         loading: Loading,
         delay: 300 // 0.3 seconds
@@ -234,7 +265,7 @@ function Loading({ error, timeOut, pastDelay }) {
 
 function App(){
   return <>
-    <DashBoard
+    <Table
       loadable={{
         loading: Loading,
         timeOut: 10000 // 10s

package/en/guides/topic-detail/micro-frontend/c05-mixed-stack.mdx

@@ -16,7 +16,7 @@ Modern.js 微前端方案是基于 [Garfish](https://garfishjs.org/) 封装的
 **Modern.js** 子应用编译后会生成标准的 [Garfish 子应用导出](https://www.garfishjs.org/guide/start#2%E5%AF%BC%E5%87%BA-provider-%E5%87%BD%E6%95%B0)。
 所以可以直接接入标准的微前端主应用。
 
-:::info 注
+:::info
 子应用是 **Modern.js**，主应用使用的原生 Garfish 微前端时，**子应用调试模式** 不可用。
 
 :::

package/en/guides/topic-detail/model/auto-actions.mdx

@@ -80,7 +80,7 @@ function Counter() {
 
 根据 `a`、`b`、`c` 三个不同的字段分别生成 `setA`、`setB`、`setC` 三个 Actions。
 
-:::info 注
+:::info
 当用户自定义的 Action 和 Modern.js 自动生成的 Action 名字一致时，用户自定义的 Action 优先级更高。例如，
 在 `countModel` 中已经自定义 `setA` 这个 Action，调用 `actions.setA()` 时，最终执行的是用户自定义的 `setA`。
 

package/en/guides/topic-detail/model/define-model.mdx

@@ -23,7 +23,7 @@ const fooModel = model('foo').define({
 });
 ```
 
-:::info 注
+:::info
 - Model 中的 Action 中不能包含有副作用的逻辑，如请求 HTTP 接口，访问 localStorage 等。
 - `setValue` 内部直接修改了入参 State，看起来是违反了纯函数的定义，实际上 Reduck 内部使用 [immer](https://github.com/immerjs/immer) 来修改不可变对象，保证了这种写法不会影响对象的不可变性，所以 `setValue` 仍然是一个纯函数。当然，你也可以直接在 Action 中返回一个新对象，不过这样的写法会更加复杂一些。
 

package/en/guides/topic-detail/model/manage-effects.mdx

@@ -187,7 +187,7 @@ const todoModel = model('todo').define((context, utils) => ({
 }));
 ```
 
-:::info 注
+:::info
 可以使用 `use` 函数加载其它 Model（包括 Model 自身），实现 [Model 间通信](/guides/topic-detail/model/model-communicate)。
 
 :::

package/en/guides/topic-detail/model/model-communicate.mdx

@@ -88,7 +88,7 @@ export default function App() {
 ```
 
 :::info 补充信息
-Modern.js 默认开启 [自动生成 actions](./auto-actions.md)，所以 `stepModel` 中虽然没有手动定义 Actions，但可以使用自动生成的 `setState`。
+Modern.js 默认开启 [自动生成 actions](./auto-actions.mdx)，所以 `stepModel` 中虽然没有手动定义 Actions，但可以使用自动生成的 `setState`。
 
 :::