@modern-js/main-doc 2.0.3-alpha.0 → 2.2.0

package/zh/apis/app/hooks/src/routes.mdx

@@ -0,0 +1,90 @@
+---
+title: routes/
+sidebar_position: 2
+---
+# routes/
+
+应用使用基于文件系统路由时的入口标识。
+
+当项目结构为 `Routes 入口` 类型时， 会分析 `src/routes` 目录下的文件得到客户端路由配置。具体用法请查看[约定式路由](/guides/basic-features/routes)
+
+任何在 `src/routes` 下的 `layout.[tj]sx` 和 `page.[tj]sx` 都会作为应用的路由：
+
+```bash {3}
+.
+└── routes
+    ├── layout.tsx
+    ├── page.tsx
+    └── user
+        ├── layout.tsx
+        └── page.tsx
+```
+
+## 基本示例
+
+`routes` 目录下的目录名会作为路由 url 的映射，其中 `layout.tsx` 中作为布局组件，`page.tsx` 作为内容组件，是整条路由的叶子节点，例如以下目录结构：
+
+```bash
+.
+└── routes
+    ├── page.tsx
+    └── user
+        └── page.tsx
+```
+
+会产出下面两条路由：
+
+- `/`
+- `/user`
+
+## 动态路由
+
+如果路由文件的目录名以 `[]` 命名，生成的路由会作为动态路由。例如以下文件目录：
+
+```
+└── routes
+    ├── [id]
+    │   └── page.tsx
+    ├── blog
+    │   └── page.tsx
+    └── page.tsx
+```
+
+`routes/[id]/page.tsx` 文件会转为 `/:id` 路由。除了可以确切匹配的 `/blog` 路由，其他所有 `/xxx` 都会匹配到该路由。
+
+在组件中，可以通过 [useParams](/apis/app/runtime/router/#useparams) 获取对应命名的参数。
+
+在 loader 中，params 会作为 [loader](/guides/basic-features/data-fetch#loader-函数) 的入参，通过 `params` 的属性可以获取到对应的参数。
+
+## 布局组件
+
+如下面的例子，可以通过添加 `layout.tsx`，为所有路由组件添加公共的布局组件：
+
+```bash
+.
+└── routes
+    ├── layout.tsx
+    ├── page.tsx
+    └── user
+        ├── layout.tsx
+        └── page.tsx
+```
+
+在布局组件中可以通过使用 `<Outlet>` 表示子组件：
+
+```tsx title=routes/layout.tsx
+import { Link, Outlet, useLoaderData } from '@modern-js/runtime/router';
+
+export default () => {
+  return (
+    <>
+      <Outlet></Outlet>
+    </>
+  );
+};
+```
+
+:::note
+`<Outlet>` 是 React Router 6 中新的 API，详情可以查看 [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
+
+:::

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

@@ -0,0 +1,34 @@
+---
+title: '*.[server|node].[tj]sx'
+sidebar_position: 8
+---
+# *.[server|node].[tj]sx
+
+应用项目中使用，用于放置服务端代码，一般有以下两个作用：
+
+1. 当 `*.tsx` 和 `*.[server|node].tsx` 共存时，SSR 在服务端执行渲染时，会优先使用 `*.[server|node].tsx` 文件，而不是 `*.tsx` 文件。
+
+2. 在使用 [data loader](/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/hooks/src/stories.mdx

@@ -0,0 +1,16 @@
+---
+title: '**/*.stories.[tj]sx'
+sidebar_position: 7
+---
+# **/*.stories.[tj]sx
+
+应用项目 Storybook 调试文件。
+
+可以在项目源码目录 `src/` 下创建 `*.stories.[tj]sx` 格式的文件作为 Storybook 的调试文件。
+
+在项目下执行 dev story 命令，支持使用这些文件在 Storybook 中对相关内容进行调试。
+
+:::info 注
+使用 Storybook 需要提前在项目下执行 new 命令启用「Visual Testing (Storybook)」模式。
+
+:::

package/zh/apis/app/hooks/src/test.mdx

@@ -0,0 +1,14 @@
+---
+title: '**/*.test.[tj]sx?'
+sidebar_position: 6
+---
+# **/*.test.[tj]sx?
+
+应用项目测试文件。
+
+应用项目支持在项目源码目录(src)下创建后缀为 `.test.[tj]sx?` 文件进行编写测试用例。
+
+:::info 注
+使用单元测试、集成测试需要提前在项目下执行 new 命令启用「单元测试 / 集成测试」功能。
+
+:::

package/zh/apis/app/runtime/app/define-config.mdx

@@ -0,0 +1,62 @@
+---
+sidebar_position: 1
+title: defineConfig
+---
+# defineConfig
+
+用于动态配置应用。
+
+## 使用姿势
+
+```ts
+import { defineConfig } from '@modern-js/runtime';
+```
+
+Runtime 配置通常可以在 `modern.config.js` 的 `runtime` 空间下配置，如 [router](/configure/app/runtime/router) 配置。
+
+`modern.config.js` 中的配置是构建时确定的，如果一些配置参数是运行时获取的，或者配置参数是来自于源码中的一个模块（如组件），就需要使用 `defineConfig` API 进行运行时配置。
+
+:::info
+`@modern-js/app-tools` 拥有同名 API，用于为配置**提供 TS 类型**，请开发者加以区分。
+
+:::
+
+## 函数签名
+
+```ts
+function defineConfig(Component, config): any;
+```
+
+### 参数
+
+- Component：`React.ComponentType<any>`，App 根组件。
+- config：`Record<string, any>`，运行时的配置。
+
+## 示例
+
+```tsx
+function App () {
+  ...
+}
+
+defineConfig(App, {
+  router: {
+    supportHtml5History: false
+  }
+})
+```
+
+1. `defineConfig` 里可配置 [runtime.state](/configure/app/runtime/state)、[runtime.router](/configure/app/runtime/router) 等运行时配置。
+
+2. `defineConfig` 在配置某个属性之前，如 `router`，需要确保 `modern.config.js` 已经配置开启了该功能。
+
+3. `defineConfig` 传入的配置会和 `modern.config.js` 中的配置浅 merge，以 `router` 为例，最终应用的配置如下：
+
+```json
+{
+  // 来自 `modern.config.js` 配置
+  ...runtime.router
+  // 来自 `defineConfig` 配置
+  ...config.router
+}
+```

package/zh/apis/app/runtime/bff/hook.mdx

@@ -0,0 +1,44 @@
+---
+title: hook
+---
+# hook
+
+用于在 BFF 函数写法下添加框架中间件，添加的中间件的执行会在 BFF 函数定义的路由之前。
+
+## 使用姿势
+
+根据使用的框架拓展插件，从对应的命名空间中导出：
+
+```ts
+import { hook } from '@modern-js/runtime/{namespace}';
+```
+
+## 函数签名
+
+```ts
+type HookOptions = {
+  addMiddleware: string | function;
+};
+
+function hook(options: HookOptions): void;
+```
+
+### 参数
+
+- `options`: Modern.js 提供的一系列钩子。
+  - `addMiddleware`: 添加 BFF 中间件的钩子。
+
+## 示例
+
+使用不同的框架，应添加不同框架的中间件（示例为使用 koa 框架时）：
+
+```ts title=api/_app.ts
+import { hook } from '@modern-js/runtime/koa';
+
+export default hook(({ addMiddleware }) => {
+  addMiddleware(async (ctx, next) => {
+    ctx.req.query.id = 'koa';
+    await next();
+  });
+});
+```

package/zh/apis/app/runtime/bff/use-context.mdx

@@ -0,0 +1,38 @@
+---
+title: useContext
+---
+# useContext
+
+用于在一体化 BFF 函数中获取请求上下文。
+
+## 使用姿势
+
+根据使用的框架拓展插件，从对应的命名空间中导出：
+
+```ts
+import { useContext } from '@modern-js/runtime/{namespace}';
+```
+
+## 函数签名
+
+`function useContext(): any`
+
+## 示例
+
+开发者可以通过 `context` 获取更多的请求信息，例如获取请求 UA（示例为使用 koa 框架时）：
+
+```ts
+import { useContext } from '@modern-js/runtime/koa';
+
+export async function get() {
+  const ctx = useContext();
+  return ctx.req.headers['user-agent'];
+}
+```
+
+:::caution 注意
+只有在一体化 BFF 函数中，你才可以使用 `useContext` API 。
+
+:::
+
+使用不同的运行时框架时，虽然均支持 `useContext` API，但它们的返回值的类型是不同的。

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

@@ -0,0 +1,70 @@
+---
+title: bootstrap
+---
+# bootstrap
+
+用于启动和挂载应用，通常情况下不做手动调用。只有在使用[自定义 App](/guides/concept/entries#自定义-app) 时，才需要使用该 API。
+
+## 使用姿势
+
+```ts
+import ReactDOM from 'react-dom/client';
+import { bootstrap } from '@modern-js/runtime';
+
+bootstrap(App, 'root', undefined, ReactDOM);
+```
+
+## 函数签名
+
+```ts
+type BootStrap<T = unknown> = (
+  App: React.ComponentType,
+  id: string | HTMLElement | RuntimeContext,
+  root?: any,
+  ReactDOM?: {
+    render?: Renderer;
+    hydrate?: Renderer;
+    createRoot?: typeof createRoot;
+    hydrateRoot?: typeof hydrateRoot;
+  },
+) => Promise<T>;
+```
+
+### 参数
+
+- `AppComponent`：通过 [`createApp`](./create-app) 创建的 ReactElement 实例。
+- `id`：要挂载的 DOM 根元素 id，如 `"root"`。
+- `root`: ReactDOM.createRoot 的返回值，用于 bootstrap 函数外需要 root 销毁组件的场景。
+- `ReactDOM`: ReactDOM 对象，用于区分 React 18 和 React 17 API。
+
+## 示例
+
+```tsx
+import ReactDOM from 'react-dom/client';
+import { createApp, bootstrap } from '@modern-js/runtime';
+
+function App() {
+  return <div>Hello Modern.js</div>;
+}
+
+const WrappedApp = createApp({
+  // 传入自定义插件
+  plugins: [customPlugin()],
+})(App);
+
+bootstrap(WrappedApp, 'root', undefined, ReactDOM);
+```
+
+:::info
+由于 `@modern-js/runtime/plugins` 是别名处理的，在 ts 项目中使用时需要声明其类型， 只需要在 `src/modern-app-env.d.ts` 添加以下类型声明即可：
+
+```ts
+declare module '@modern-js/runtime/plugins';
+```
+
+:::
+
+:::warning
+bootstrap 只支持在 CSR 场景下使用。
+
+:::

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

@@ -0,0 +1,31 @@
+---
+title: createApp
+---
+# createApp
+
+用于创建自定义入口，定制运行时插件。只有在使用[自定义 App](/guides/concept/entries#自定义-app) 时，才需要使用该 API。
+
+## 使用姿势
+
+```ts
+import { createApp } from '@modern-js/runtime';
+```
+
+## 函数签名
+
+```ts
+import type { Plugin } from '@modern-js/runtime';
+
+function createApp(options: { plugins: Plugin[] }): React.ComponentType<any>;
+```
+
+### 参数
+
+- `options`: 可选的参数。
+  - `plugins`：自定义的插件扩展。
+
+## 示例
+
+### 创建自定义入口
+
+详见 [`bootstrap`](./bootstrap.md)。

package/zh/apis/app/runtime/core/use-loader.mdx

@@ -0,0 +1,85 @@
+---
+title: useLoader
+---
+# useLoader
+
+一个同构的 API，通常会用来做异步请求。当 SSR 的时候，服务端使用 `useLoader` 预加载数据，同时浏览器端也会复用这部分数据。
+
+## 使用姿势
+
+```ts
+import { useLoader } from '@modern-js/runtime';
+```
+
+## 函数签名
+
+```ts
+type LoaderFn = (context: runtimeContext) => Promise<unknow>;
+type Options = {
+  onSuccess: (data: Record<string, any>) => void;
+  onError: (error: Error) => void;
+  initialData: Record<string, any>;
+  skip: boolean;
+  params: Record<string, any>;
+  static: boolean;
+};
+type ReturnData = {
+  data: Record<string, any>;
+  loading: boolean;
+  error: Error;
+  reload: (params?: Record<string, any>) => Promise<any> | undefined;
+  reloading: boolean;
+};
+
+function useLoader(loaderFn: LoaderFn, options: Options): ReturnData;
+```
+
+:::info
+`runtimeContext` 类型可以参考 [useRuntimeContext](/apis/app/runtime/core/use-runtime-context)。
+
+:::
+
+### 参数
+
+- `loaderFn`：用于加载数据的函数，返回 Promise。
+- `options`：可选配置项。
+  - `onSuccess`：执行成功的回调。
+  - `onError`：执行失败的回调。
+  - `initialData`：首次执行前的初始数据，对应返回值中的 `data` 字段。
+  - `skip`：当值为 `true` 时，函数不执行。
+  - `params`：当 `params` 序列化结果发生改变时，函数会重新执行。同时，`params` 也会作为函数的第二个参数被传入。
+  - `static`：当值为 `true` 时，`useLoader` 用于 [SSG](/guides/advanced-features/ssg) 编译阶段数据的获取。
+
+### 返回值
+
+- `data`：执行成功时的返回数据。
+- `loading`：表示函数是否处于执行过程中。
+- `error`：函数执行失败时的错误信息。
+- `reload`：调用后可以重新执行函数。
+  - `params`：当值为 `undefined` 时，函数执行时将复用上次的值；否则会使用新的值重新执行函数。
+- `reloading`：调用 `reload` 的执行过程中，`reloading` 值为 `true`。
+
+## 示例
+
+```ts
+function Container() {
+  const { data, error, loading } = useLoader(
+    async (context, params) => {
+      console.log(params) // nicole
+      return fetch(user);
+    },
+    {
+      onSuccess: data => {
+        console.log('I did success:(',  data);
+      },
+      onError: error => {
+        console.log('I met error:)',  error);
+      },
+      initialData: { name: 'nicole', gender: 'female' },
+      params: 'nicole'
+    }
+  );
+
+  return ...;
+}
+```

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

@@ -0,0 +1,138 @@
+---
+title: useModuleApps
+---
+# useModuleApps
+
+返回所有微前端子应用的 React 组件，用于可自由控制路由。
+
+## 使用姿势
+
+```tsx
+import { useModuleApps } from '@modern-js/plugin-garfish/runtime';
+```
+
+## 函数签名
+
+`function useModuleApps(): Record<string, React.FC<any>>`
+
+分别返回包裹每个子应用后的 React 组件。
+
+## 示例
+
+需要先配置微前端子应用信息。
+
+import EnableMicroFrontend from "@site-docs/components/enable-micro-frontend";
+
+<EnableMicroFrontend />
+
+```tsx title=App.tsx
+function App() {
+  const { Home, Contact } = useModuleApps();
+
+  return (
+    <div>
+      Master APP
+      <Route exact path="/home">
+        <Home />
+      </Route>
+      <Route exact path="/home">
+        <Contact />
+      </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` 字段来启用 **集中式路由**。
+
+import MicroRuntimeConfig from "@site-docs/components/micro-runtime-config";
+
+<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 { Home } = useModuleApps();
+
+  return (
+    <div>
+      Master APP
+      <Route exact path="/home">
+        <Home
+          loadable={{
+            loading: ({ pastDelay, error }: any) => {
+              if (error) {
+                console.error(error);
+                return <div>error: {error?.message}</div>;
+              } else if (pastDelay) {
+                return <div>loading</div>;
+              } else {
+                return null;
+              }
+            },
+          }}
+        />
+      </Route>
+    </div>
+  );
+}
+```

package/zh/apis/app/runtime/core/use-runtime-context.mdx

@@ -0,0 +1,59 @@
+---
+title: useRuntimeContext
+---
+# useRuntimeContext
+
+该函数主要用于获取 Runtime 上下文，只能在函数组件中使用。
+
+## 使用姿势
+
+```tsx
+import { useRuntimeContext } from '@modern-js/runtime';
+
+export function App() {
+  const runtimeContext = useRuntimeContext();
+  return <div>Hello World</div>;
+}
+```
+
+## 函数签名
+
+```ts
+type RuntimeContext = {
+  request: {
+    params: Record<string, string>;
+    pathname: string;
+    query: Record<string, string>;
+    headers: IncomingHttpHeaders;
+    cookie: string;
+  };
+  store: ReduckStore;
+};
+
+function useRuntimeContext(): RuntimeContext;
+```
+
+### 返回值
+
+- `request`：请求上下文中的附加信息。
+  - `params`：请求路径中的动态参数。
+  - `pathname`：请求的 pathname。
+  - `query`：请求的查询字符串对象。
+  - `headers`：请求头信息。
+  - `cookie`：请求的 cookie 信息。
+- `store`：在开启了 state 插件的时候，该值为 reduck 全局 `store`。
+
+## 示例
+
+```tsx
+import { useRuntimeContext } from '@modern-js/runtime';
+import { fooModel } from '@/common/models';
+
+function App() {
+  const { store } = useRuntimeContext();
+
+  const [state, actions] = store.use(fooModel);
+
+  return <div>state: {state}</div>;
+}
+```

package/zh/apis/app/runtime/index.mdx

@@ -0,0 +1,7 @@
+---
+type: ref
+---
+
+# 运行时
+
+本节涵盖了使用 `@modern-js/runtime` 的所有 API。