@modern-js/main-doc 2.0.0-beta.4 → 2.0.0-beta.5

package/zh/apis/app/hooks/src/server.md

@@ -0,0 +1,31 @@
+---
+title: "*.[server|node].[tj]sx"
+sidebar_position: 8
+---
+
+应用项目中使用，用于放置服务端代码，一般有以下两个作用：
+
+1. 当 `*.tsx` 和 `*.[server|node].tsx` 共存时，SSR 在服务端执行渲染时，会优先使用 `*.[server|node].tsx` 文件，而不是 `*.tsx` 文件。
+
+2. 在使用 [data loader](/docs/guides/basic-features/data-fetch) 时，需要将服务端的依赖从该文件中做重导出
+
+```tsx
+// routes/user/avatar.tsx
+import { useLoaderData } from '@modern-js/runtime/router';
+import { readFile } from './utils.server';
+
+type ProfileData = { /* some type declarations */ }
+
+export const loader = async(): ProfileData => {
+  const profile = await readFile('profile.json');
+  return profile;
+}
+
+export default function UserPage() {
+  const profileData = useLoaderData() as ProfileData;
+  return <div>{profileData}</div>;
+}
+
+// routes/user/utils.server.ts
+export * from 'fs-extra';
+```

package/zh/apis/app/runtime/core/bootstrap.md

@@ -2,7 +2,7 @@
 title: bootstrap
 ---
 
-用于启动和挂载应用，通常情况下不做手动调用。只有在使用[自定义入口](/docs/guides/advanced-features/custom-app)时，才需要使用该 API。
+用于启动和挂载应用，通常情况下不做手动调用。只有在使用[自定义 App](/docs/guides/concept/entries#自定义-app) 时，才需要使用该 API。
 
 ## 使用姿势
 
@@ -32,7 +32,7 @@ type BootStrap<T = unknown> = (
 ### 参数
 
 - `AppComponent`：通过 [`createApp`](./create-app) 创建的 ReactElement 实例。
-- `rootId`：要挂载的 DOM 根元素 id，如 `"root"`。
+- `id`：要挂载的 DOM 根元素 id，如 `"root"`。
 - `root`: ReactDOM.createRoot 的返回值，用于 bootstrap 函数外需要 root 销毁组件的场景。
 - `ReactDOM`: ReactDOM 对象，用于区分 React 18 和 React 17 API。
 
@@ -41,7 +41,6 @@ type BootStrap<T = unknown> = (
 ```tsx
 import ReactDOM from 'react-dom/client'
 import { createApp, bootstrap } from '@modern-js/runtime';
-import { router, state } from '@modern-js/runtime/plugins';
 
 function App() {
   return <div>Hello Modern.js</div>;
@@ -49,7 +48,7 @@ function App() {
 
 const WrappedApp = createApp({
   // 传入自定义插件
-  plugins: [router({}), state({})],
+  plugins: [customPlugin()],
 })(App);
 
 bootstrap(WrappedApp, 'root', undefined, ReactDOM);

package/zh/apis/app/runtime/core/create-app.md

@@ -2,7 +2,7 @@
 title: createApp
 ---
 
-用于创建自定义入口，定制运行时插件。只有在使用[自定义入口](/docs/guides/advanced-features/custom-app)时，才需要使用该 API。
+用于创建自定义入口，定制运行时插件。只有在使用[自定义 App](/docs/guides/concept/entries#自定义-app) 时，才需要使用该 API。
 
 ## 使用姿势
 
@@ -28,20 +28,3 @@ function createApp(options: { plugins: Plugin[] }): React.ComponentType<any>;
 ### 创建自定义入口
 
 详见 [`bootstrap`](./bootstrap.md)。
-
-### 定制插件
-
-```ts
-import { createApp } from '@modern-js/runtime';
-
-function App() {
-  return <div>app</div>;
-}
-
-export default createApp({
-  plugins: [
-    router({}),
-    state({}),
-  ]
-})(App);
-```

package/zh/apis/app/runtime/core/use-module-apps.md

@@ -7,19 +7,9 @@ title: useModuleApps
 ## 使用姿势
 
 ```tsx
-import { useModuleApps } from '@modern/plugin-garfish';
+import { useModuleApps } from '@modern-js/runtime/garfish';
 ```
 
-:::info 开启微前端
-该 API 在微前端主应用中使用，请先执行 `pnpm run new` 开启微前端功能。
-
-```bash
-pnpm run new
-? 请选择你想要的操作 启用可选功能
-? 启用可选功能 启用「微前端」模式
-```
-:::
-
 ## 函数签名
 
 `function useModuleApps(): Record<string, React.FC<any>>`
@@ -29,31 +19,14 @@ pnpm run new
 ## 示例
 
 需要先配置微前端子应用信息。
+import EnableMicroFrontend from '@site-docs/components/enable-micro-frontend.md';
+
+<EnableMicroFrontend />
 
-```ts title=modern.config.js
-module.exports = {
-  runtime: {
-    features:{
-      masterApp: {
-        apps: [
-          {
-            name: 'Home',
-            entry: 'http://www.home.com'
-          },
-          {
-            name: 'Contact',
-            entry: 'http://www.contact.com'
-          },
-        ]
-      }
-    }
-  }
-}
-```
 
 ```tsx title=App.tsx
 function App() {
-  const { Components: { Home, Contact } } = useModuleApps();
+  const { Home, Contact } = useModuleApps();
 
   return <div>
     Master APP
@@ -65,18 +38,76 @@ function App() {
     </Route>
   </div>;
 }
+
+defineConfig(App, {
+  masterApp: {
+    apps: [
+      {
+        // name 区分大小写，name 提供的是什么 useModuleApps 返回的就是什么
+        name: "Home",
+        entry: "http://127.0.0.1:8081/"
+      },
+      {
+          name: "Contact",
+          entry: "http://localhost:8082"
+      }
+    ]
+  }
+})
 ```
 
 通过 `useModuleApps()` 获取到 `Home` 和 `Contact` 子应用组件（名称和配置里的 `name` 字段对应），之后就可以像使用普通的 React 组件一样去加载子应用。
 
 
+### 集中式路由
+
+**集中式路由** 是将子应用的激活路由集中配置的方式。我们给子应用列表信息添加 `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>
+}
+
+defineConfig(App, {
+  masterApp: {
+    apps: [
+      {
+        // name 区分大小写，name 提供的是什么 useModuleApps 返回的就是什么
+        name: "Dashboard",
+        activeWhen: '/dashboard',
+        entry: "http://127.0.0.1:8081/"
+      },
+      {
+        name: "TableList",
+        activeWhen: '/table',
+        entry: "http://localhost:8082"
+      }
+    ]
+  }
+})
+```
+
+这样启动应用后，访问 `/dashboard` 路由，会渲染 `Dashboard` 子应用，访问 `/table` 路由，会渲染 `TableList` 子应用。
+
+
 ## 加载动画
 
 可以通过以下方式，自定义组件加载过程的过渡动画。
 
 ```tsx title=App.tsx
 function App() {
-  const { Components: { Home } } = useModuleApps();
+  const { Home } = useModuleApps();
 
   return <div>
     Master APP

package/zh/apis/app/runtime/web-server/hook.md

@@ -46,6 +46,7 @@ type HookContext = {
     ) => void;
   };
   request: {
+    url: string;
     host: string;
     pathname: string;
     query: Record<string, any>;
@@ -82,7 +83,6 @@ type AfterRenderContext = {
 };
 ```
 
-
 ### 参数
 
 - `context`：提供当前 Hook 上下文。

package/zh/apis/app/runtime/web-server/middleware.md

@@ -53,6 +53,7 @@ type MiddlewareContext = {
     locals: Record<string, any>;
   };
   request: {
+    url: string;
     host: string;
     pathname: string;
     query: Record<string, any>;

package/zh/components/default-mwa-generate.md

@@ -0,0 +1,5 @@
+```bash
+? 请选择你想创建的工程类型 应用
+? 请选择开发语言 TS
+? 请选择包管理工具 pnpm
+```

package/zh/components/deploy.md

@@ -0,0 +1 @@
+本地验证完成后，可以将 `dist/` 下的产物整理成服务器需要的结构，进行部署。

package/zh/components/enable-micro-frontend.md

@@ -0,0 +1,13 @@
+```javascript title="modern.config.ts"
+import AppToolPlugin, { defineConfig } from '@modern-js/app-tools';
+import GarfishPlugin from '@modern-js/plugin-garfish';
+
+export default defineConfig({
+  runtime: {
+    router: true,
+    state: true,
+    masterApp: true,
+  },
+  plugins: [AppToolPlugin(), GarfishPlugin()],
+});
+```

package/zh/components/init-app.md

@@ -15,8 +15,8 @@ Modern.js 生成器会提供一个可交互的问答界面，根据结果初始
 [INFO] 创建成功！
 可在新项目的目录下运行以下命令：
 pnpm run dev          # 按开发环境的要求，运行和调试项目
-pnpm run build        # 按产品环境的要求，构建项目
-pnpm run start        # 按产品环境的要求，运行项目
+pnpm run build        # 按生产环境的要求，构建项目
+pnpm run serve        # 按生产环境的要求，运行项目
 pnpm run lint         # 检查和修复所有代码
 pnpm run new          # 继续创建更多项目要素，比如应用入口
 ```

package/zh/components/micro-runtime-config.md

@@ -0,0 +1,18 @@
+```javascript title="src/App.tsx"
+import { defineConfig } from '@modern-js/runtime';
+
+defineConfig(App, {
+  masterApp: {
+    apps: [
+      {
+        name: 'DashBoard',
+        entry: 'http://127.0.0.1:8081/',
+      },
+      {
+        name: 'TableList',
+        entry: 'http://localhost:8082',
+      },
+    ],
+  },
+});
+```

package/zh/components/prerequisites.md

@@ -1,10 +1,10 @@
 ### Node.js
 
-需要 [Node.js LTS](https://github.com/nodejs/Release)，并确保 Node 版本大于等于 16.18.1
+需要 [Node.js LTS](https://github.com/nodejs/Release)，并确保 Node 版本大于等于 v16.18.1。
 
 Modern.js 推荐在开发环境里先安装 [nvm](https://github.com/nvm-sh/nvm#install--update-script)，在 shell 里集成[自动切换 node 版本的脚本](https://github.com/nvm-sh/nvm#deeper-shell-integration)。
 
-然后只要仓库根目录下有内容为 `lts/fermium` 或 `lts/gallium` 的 `.nvmrc` 文件，进入这个仓库时就会自动安装或切换到正确的 Node.js 版本。
+然后只要仓库根目录下有内容为 `lts/gallium` 的 `.nvmrc` 文件，进入这个仓库时就会自动安装或切换到正确的 Node.js 版本。
 
 ### pnpm
 

package/zh/components/release-note.md

@@ -0,0 +1 @@
+根据官网 [Release Note](https://github.com/modern-js-dev/modern.js/releases/tag/v1.22.1)，开发者也可以手动将项目升级到想要的版本。

package/zh/configure/app/builder-plugins.md

@@ -0,0 +1,72 @@
+---
+title: builderPlugins (构建插件)
+sidebar_position: 10
+---
+
+- 类型：`BuilderPlugin[]`
+- 默认值：`[]`
+
+用于配置 Modern.js Builder 构建插件。
+
+Modern.js Builder 是 Modern.js 底层的构建引擎，请阅读 [构建能力](/docs/guides/basic-features/builder) 了解相关背景。
+
+如果你想了解 Builder 插件的编写方式，可以参考 [Modern.js Builder - 插件系统](https://modernjs.dev/builder/zh/plugins/introduction.html)。
+
+## 注意事项
+
+该选项**用于配置 Modern.js Builder 构建插件**，如果你需要配置其他类型的插件，请选择对应的配置方式：
+
+- 配置 Modern.js 框架插件，请使用 [plugins](docs/configure/app/plugins) 配置项。
+- 配置 webpack 插件，请使用 [tools.webpack](/docs/configure/app/tools/webpack) 或 [tools.webpackChain](/docs/configure/app/tools/webpack-chain) 配置项。
+- 配置 Babel 插件，请使用 [tools.babel](/docs/configure/app/tools/babel) 配置项。
+
+## 何时使用
+
+大部分场景下，我们推荐你使用 Modern.js 框架插件，框架插件可以通过 [plugins](docs/configure/app/plugins) 字段进行注册。因为框架插件提供的 API 更丰富、能力更强，而 Builder 插件提供的 API 只能用于构建场景。
+
+当你需要引用一些现有的 Builder 插件（并且在 Modern.js 中没有相关能力），或是在不同的框架之间复用 Builder 插件时，你可以使用 `builderPlugins` 字段进行注册。
+
+## 示例
+
+下面是 Builder 插件的使用示例。
+
+### 使用 npm 上的插件
+
+使用 npm 上的插件，需要通过包管理器安装插件，并通过 import 引入。
+
+```ts title="modern.config.ts"
+import MyBuilderPlugin from 'my-builder-plugin';
+
+export default defineConfig({
+  builderPlugins: [MyBuilderPlugin()],
+});
+```
+
+### 使用本地插件
+
+使用本地代码仓库中的插件，直接通过相对路径 import 引入即可。
+
+```ts title="modern.config.ts"
+import MyBuilderPlugin from './plugin/myBuilderPlugin';
+
+export default defineConfig({
+  builderPlugins: [MyBuilderPlugin()],
+});
+```
+
+### 插件配置项
+
+如果插件提供了一些自定义的配置项，可以通过插件函数的参数传入配置。
+
+```ts title="modern.config.ts"
+import MyBuilderPlugin from 'my-builder-plugin';
+
+export default defineConfig({
+  builderPlugins: [
+    MyBuilderPlugin({
+      foo: 1,
+      bar: 2,
+    }),
+  ],
+});
+```

package/zh/configure/app/deploy/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "deploy (部署)",
+  "position": 8
+}

package/zh/configure/app/deploy/microFrontend.md

@@ -0,0 +1,64 @@
+---
+sidebar_label: microFrontend
+---
+
+# deploy.microFrontend
+
+* 类型：`object`
+* 默认值：`{enableHtmlEntry: true, externalBasicLibrary: false}`
+
+```ts
+interface MicroFrontend {
+  enableHtmlEntry?: boolean;
+  externalBasicLibrary?: boolean;
+  moduleApp?: string;
+}
+```
+
+开发者可使用 `deploy.microFrontend` 属性来配置微前端子应用的信息。
+
+:::caution 注意
+需要先通过 `pnpm run new` 启用「微前端」 功能。
+:::
+
+## 示例
+
+```ts
+export default defineConfig({
+  deploy: {
+    microFrontend: {
+      enableHtmlEntry: true
+    }
+  }
+});
+```
+
+## 配置项
+
+### enableHtmlEntry
+
+* 类型：`boolean`
+
+* 默认值：`true`
+
+* 是否启用 html 入口的功能，默认为 `true`，将子应用构建成 `HTML` 模式，Garfish 支持了 `html` 入口，可以开启开选项，体验对应功能，为 HTML 入口时直接将子应用 entry 指向子应用的 html 即可
+* 可以通过设置为 `false`, 表明子应用构建为 `js`，构建为 `js` 后子应用无法独立运行，为 `JS` 入口时将子应用的入口文件指向子应用的 `JS`
+
+
+### externalBasicLibrary
+
+* 类型：`boolean`
+
+* 默认值：`false`
+
+是否 `external` 基础库，当设置为 `true` 时，当前子应用将会 `external`：`react`、`react-dom`，`EdenX` 主应用会自动 `setExternal` 这两个基础库，如果其他类型的框架请通过 `Garfish.setExternal` 增加 `react`、`react-dom` 依赖
+
+
+### moduleApp
+
+* 类型：`string`
+
+* 默认值：`undefined`
+
+该值可以配置子应用的名称，目前主要结合 [`dev.withMasterApp`](/docs/configure/app/dev/with-master-app) 进行测试。
+

package/zh/configure/app/dev/with-master-app.md

@@ -30,5 +30,3 @@ export default defineConfig({
 
 - moduleApp: `string` 主应用的线上地址。
 - moduleName: `Contact` 子应用的名称（需要和在主应用中注册的模块名匹配）。
-
-详细使用方式，请参考【[微前端子应用](/docs/guides/topic-detail/micro-frontend/debugging)】。

package/zh/configure/app/plugins.md

@@ -3,18 +3,24 @@ title: plugins (插件)
 sidebar_position: 9
 ---
 
-- 类型： `CliPlugin[]`
+- 类型：`CliPlugin[]`
 - 默认值：`[]`
 
-用于配置自定义的 Modern.js 插件。
+用于配置自定义的 Modern.js 框架插件。
 
 自定义插件的编写方式请参考 [如何编写插件](/docs/guides/topic-detail/framework-plugin/implement)。
 
-该选项用于配置框架插件，如果需要配置 webpack 插件，请使用 [tools.webpack](/docs/configure/app/tools/webpack) 或 [tools.webpackChain](/docs/configure/app/tools/webpack-chain); 需要配置 babel 插件，请使用 [tools.babel](/docs/configure/app/tools/babel)。
+## 注意事项
+
+该选项**用于配置框架插件**，如果你需要配置其他类型的插件，请选择对应的配置方式：
+
+- 配置 Modern.js Builder 插件，请使用 [builderPlugins](docs/configure/app/builder-plugins) 配置项。
+- 配置 webpack 插件，请使用 [tools.webpack](/docs/configure/app/tools/webpack) 或 [tools.webpackChain](/docs/configure/app/tools/webpack-chain) 配置项。
+- 配置 Babel 插件，请使用 [tools.babel](/docs/configure/app/tools/babel) 配置项。
 
 ## 插件类型
 
-Modern.js 中内置了三种不同的插件机制：
+Modern.js 中内置了三种不同的框架插件：
 
 - `CLI 插件`，适用于本地开发、编译构建阶段，可以在命令行和编译阶段扩展各种能力。
 - `Server 插件`，适用于服务端。

package/zh/configure/app/runtime/master-app.md

@@ -6,54 +6,51 @@ sidebar_label: masterApp
 
 * 类型： `Object`
 
-:::info
-使用该配置首先需要使用 [new 命令](/docs/apis/app/commands/new)启用「微前端」功能。
+:::caution 注意
+需要先通过 `pnpm run new` 启用「微前端」 功能。
 :::
-## `manifest`
 
-主应用添加子应用信息。
+## 示例
 
-* 类型：`modules: Array<{
-        name: string;
-        entry: string;
-        activeWhen?: string;
-      }> | string;`
-* 默认值：`null`
+import EnableMicroFrontend from '@site-docs/components/enable-micro-frontend.md';
 
-### `modules`
+<EnableMicroFrontend />
 
-当 `modules` 为对象类型的时候，表示子应用模块的信息。
+## `manifest`
 
-- name: 子应用的名称。
-- entry: 子应用的入口。
-- activeWhen?: 子应用激活路径。
+```ts
+interface Manifest {
+  getAppList?: ()=> Array<AppInfo>
+}
+```
 
-当 `modules` 为 `string` 时，是一个 url 地址，请求该地址可以拿到和 `modules` 对象格式一样的数据结构。
+#### `getAppList?`
 
-## `LoadingComponent`
+通过 `getAppList` 配置，可以自定义如何获取远程列表数据
 
-* 类型: `React.ComponentType | React.ElementType`
-* 默认值 `null`
+```ts
+type GetAppList = ()=> Promise<Array<AppInfo>>;
+```
 
-当加载或切换子应用的时候，加载的过渡动画。
 
-`LoadingComponent` 需要通过 [defineConfig](/docs/apis/app/runtime/app/define-config) 配置。
+### apps
 
-```tsx
-import { defineConfig } from '@modern-js/runtime';
+当 `apps` 为对象类型的时候，表示子应用模块的信息 `Array<AppInfo>`
 
-function App() {
-  ...
+```ts
+interface AppInfo {
+  name: string;
+  entry: string;
+  activeWhen?: string | ()=> boolean;
 }
-
-defineConfig(
-  App,
-  {
-    masterApp: {
-      LoadingComponent: () => {
-        return <div>loading...</div>
-      }
-    }
-  }
-)
 ```
+
+- name: 子应用的名称。
+- entry: 子应用的入口。
+- activeWhen?: 子应用激活路径。
+
+### 其他配置项
+
+在 `masterApp` 配置下，开发者可以透传 Garfish 的配置项。
+
+所有支持的配置项[点此查看](https://garfishjs.org/api/run/#%E5%8F%82%E6%95%B0)

package/zh/configure/app/source/disable-entry-dirs.md

@@ -0,0 +1,37 @@
+---
+title: source.disableEntryDirs
+
+sidebar_label: disableEntryDirs
+---
+
+* 类型： `string[]`
+* 默认值： `[]`
+
+默认会根据 `src` 目录识别应用入口，可通过该选项禁止某些目录被识别为应用入口。
+
+例如，当配置与目录结构如下时：
+
+```typescript title="modern.config.ts"
+export default defineConfig({
+  source: {
+    disableEntryDirs: './src/one'
+  }
+})
+```
+
+``` title="项目目录结构"
+└── src/
+    ├── one/
+    |    └── App.tsx
+    ├── two/
+    |    └── routes/
+    └── env.d.ts
+```
+
+在未设置该配置项时，Modern.js 会根据项目目录产出两个 entry:
+- one
+- two
+
+当设置该配置项后，`src/one` 不会作为 entry 目录被识别。
+
+常见的用法是，将 `src/common`、`src/components` 目录配置到该选项中，避免这些目录被识别为应用入口。

package/zh/configure/app/source/entries-dir.md

@@ -4,12 +4,9 @@ title: source.entriesDir
 sidebar_label: entriesDir
 ---
 
-
-
 * 类型： `string`
 * 默认值： `./src`
 
-
 默认会根据 `src` 目录识别应用入口，可通过该选项自定义应用入口的识别目录。
 
 例如，当配置与目录结构如下时：