@modern-js/main-doc 0.0.0-next-20221116121040

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

@@ -0,0 +1,64 @@
+---
+title: useModuleApps
+sidebar_position: 7
+---
+
+:::info 补充信息
+返回所有微前端子应用的 React 组件，用于可自由控制路由。
+```ts
+import { useModuleApps } from '@modern-js/plugin-garfish';
+```
+:::
+
+:::caution 注意
+该 API 在微前端主应用中使用，需要先开启微前端。
+:::
+
+## API
+
+`useModuleApps() => Record<string, React.FC<any>>`
+
+分别返回包裹每个子应用后的 React 组件。
+
+## 示例
+
+需要先配置微前端子应用信息。
+
+```js title=modern.config.js
+defineConfig({
+  runtime: {
+    masterApp: {
+      manifest: {
+        modules: [
+          {
+            name: 'Home',
+            entry: 'http://www.home.com'
+          },
+          {
+            name: 'Contact',
+            entry: 'http://www.contact.com'
+          },
+        ]
+      }
+    }
+  }
+})
+```
+
+```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>;
+}
+```
+
+通过 `useModuleApps()` 获取到 `Home` 和 `Contact` 子应用组件（名称和配置里的 `name` 字段对应），之后就可以像使用普通的 React 组件一样去加载子应用。

package/zh/apis/app/runtime/app/use-runtime-context.md

@@ -0,0 +1,39 @@
+---
+sidebar_position: 2
+---
+# useRuntimeContext
+
+:::info 补充信息
+在 `React` 组件中获取 runtime 上下文，其中包含 `request` 和 `store` 实例。
+```ts
+import { useRuntimeContext } from '@modern-js/runtime';
+```
+:::
+
+## API
+
+`useRuntimeContext() => RuntimeContext`
+### 返回值
+
+- request：`object`，请求上下文中的附加信息。
+  - params：`Record<string, string>`，请求路径中的动态参数。
+  - pathname：`string`，请求的 pathname。
+  - query：`Record<string, string>`，请求的查询字符串对象。
+  - headers：`IncomingHttpHeaders`，请求头信息。
+  - [cookie]：`string`，请求的 cookie 信息。
+- store：`ReduckStore`，在开启了 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/bff-server/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "BFF Server API",
+  "position": 4
+}

package/zh/apis/app/runtime/bff-server/after-lambda-registed.md

@@ -0,0 +1,35 @@
+# afterLambdaRegisted
+
+:::info 补充信息
+`afterLambdaRegisted` hook 可以在 express 框架模式下，添加代码逻辑，该 hook 中的代码会在 BFF 函数注册路由后执行，可以用于添加中间件，错误处理等。
+:::
+
+
+## API
+
+`export const afterLambdaRegisted = (app: Express) => void`
+
+### 参数
+- app: `Express`，Express 实例。
+
+## 示例
+```ts title=api/app.ts
+const app = express();
+// 其他代码...
+export default app;
+
+export const afterLambdaRegisted = (app: Express) => {
+  const errorHandler = (
+    err: Error,
+    req: Request,
+    res: Response,
+    next: NextFunction,
+  ) => {
+    if (res.headersSent) {
+      return next(err);
+    }
+    res.status(500).send('some error message');
+  }
+  app.use(errHandler);
+}
+```

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

@@ -0,0 +1,120 @@
+---
+sidebar_position: 3
+---
+
+# hook
+
+:::info 补充信息
+用于在 BFF 函数写法下添加框架中间件，添加的中间件的执行会在**BFF函数**定义的路由之前。
+```ts
+import { hook } from '@modern-js/runtime/server';
+```
+:::
+
+## API
+
+`hook(options) => void`
+
+### 参数
+
+- options: `object`，Modern.js 提供的一系列钩子。
+  - [addMiddleware]: `string | function`，添加中间件的钩子。
+
+## 示例
+
+使用不同的框架，应添加不同框架的中间件。目前支持 **express**、**nest**、**koa** 和 **egg**。
+### Express
+
+```ts title=api/_app.ts
+import { hook } from '@modern-js/runtime/server';
+
+export default hook(({ addMiddleware }) => {
+  addMiddleware(async (req, res, next) => {
+    req.query.id = 'express';
+    await next();
+  });
+});
+```
+
+### Nest
+
+#### 添加中间件
+
+```ts title=api/_app.ts
+import { hook } from '@modern-js/runtime/server';
+
+export default hook(({ addMiddleware }) => {
+  addMiddleware(async (req, res, next) => {
+    req.query.id = 'express';
+    await next();
+  });
+});
+```
+
+#### 添加 Module
+
+```ts title=api/_app.ts
+import { hook } from '@modern-js/runtime/server';
+import {
+  Injectable,
+  MiddlewareConsumer,
+  Module,
+  NestMiddleware,
+} from '@nestjs/common';
+
+@Injectable()
+export class LoggerMiddleware implements NestMiddleware {
+  async use(req: any, res: any, next: any) {
+      console.info(`access url: ${req.url}`);
+      next();
+  }
+}
+
+@Module()
+export class AppModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer.apply(LoggerMiddleware).forRoutes('*');
+  }
+}
+
+export default hook(({ addMiddleware }) => {
+  addMiddleware(AppModule);
+});
+```
+
+### Koa
+
+```ts title=api/_app.ts
+export default hook(({ addMiddleware }) => {
+  addMiddleware(async (ctx, next) => {
+    ctx.req.query.id = 'koa';
+    await next();
+  });
+});
+```
+
+### egg
+
+#### 添加中间件
+
+```ts title=api/_app.ts
+export default hook(({ addMiddleware }) => {
+  addMiddleware(() => async (ctx, next) => {
+    ctx.req.query.id = 'egg';
+    await next();
+  });
+});
+```
+
+#### 给中间件注入参数
+
+```ts title=api/_app.ts
+export default hook(({ addMiddleware }) => {
+  addMiddleware([
+    'eggMiddleware',        // 这里为第三方 node_module 包名
+    {
+      key: 'value',
+    },
+  ])
+});
+```

package/zh/apis/app/runtime/bff-server/use-context.md

@@ -0,0 +1,70 @@
+---
+sidebar_position: 1
+---
+
+# useContext
+
+:::info 补充信息
+用于在一体化 BFF 函数中获取请求上下文。
+```ts
+import { useContext } from '@modern-js/runtime/server';
+```
+:::
+
+## API
+
+`useContext() => any`
+
+## 示例
+
+开发者可以通过 `context` 获取更多的请求信息，例如获取请求 UA(示例为使用 koa 框架时)：
+
+```ts
+import { useContext } from '@modern-js/runtime/server';
+
+export async function get() {
+  const ctx = useContext();
+  return ctx.req.headers['user-agent'];
+}
+```
+
+:::caution 注意
+只有在一体化 BFF 函数中，你才可以使用 `useContext` API 。
+:::
+
+
+## 框架差异
+
+在 Modern.js 中 **Express**、**Nest**、**Koa**、**Egg** 等运行时框架均支持 `useContext` API，但它们的返回值的类型是不同的。
+
+### Express
+
+```ts
+import { Request, Response } from 'express';
+
+export type Context = { req: Request; res: Response };
+```
+
+### Nest
+
+```ts
+import type { Request, Response } from 'express';
+import type { FastifyRequest } from 'fastify';
+
+export type Context = {
+  request: Request & FastifyRequest;
+  response: Response;
+};
+```
+
+### Koa
+
+```ts
+export type { Context } from 'koa';
+```
+
+### Egg
+
+```ts
+export type { Context } from 'egg';
+```

package/zh/apis/app/runtime/container/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Container API",
+  "position": 5
+}