@modern-js/main-doc 2.0.0-beta.0 → 2.0.0-beta.1

package/zh/apis/app/runtime/app/no-ssr.md

@@ -1,41 +0,0 @@
----
-title: NoSSR
-sidebar_position: 4
----
-
-:::info 补充信息
-被 NoSSR 包裹的内容在服务端不会进行渲染，在客户端 hydrate 阶段也不会渲染，等到整个 App mount 后便会立即渲染。
-```ts
-import { NoSSR } from '@modern-js/runtime/ssr';
-```
-:::
-
-## API
-
-```tsx
-<NoSSR></NoSSR>
-```
-
-## 示例
-
-下列代码中，`Time` 组件用于展示当前的时间，由于服务端渲染和客户端 hydrate 时获取到的时间是不一致的，react 就会抛出异常。针对这种情况可以使用 `NoSSR` 进行优化：
-
-```tsx
-import { NoSSR } from '@modern-js/runtime/ssr';
-
-function Time() {
-  return <NoSSR>
-    <div>Time: { Date.now() }</div>
-  </NoSSR>
-}
-```
-
-## 使用场景
-
-在 CSR 中，常常需要根据当前浏览器 UA，或是当前页面 URL 的某个参数的不同，来渲染不同的内容。
-
-如果此时应用直接切换到 SSR，很有可能出现不符合预期的结果。
-
-Modern.js 在 SSR 上下文中提供了完整的浏览器端信息，合理利用上下文信息来决定组件在服务端的渲染结果，避免出现 Jarring Render。
-
-如果应用里有太多的判断，希望以后再使用上下文；或者不希望某些内容在服务端被渲染，可以使用 NoSSR 组件将这一部分剔除在服务端渲染外。

package/zh/apis/app/runtime/app/pre-render.md

@@ -1,77 +0,0 @@
----
-title: PreRender
-sidebar_position: 5
----
-
-:::info 补充信息
-无展示内容的高阶组件，通过类似 Helmet 的方式实现 SPA 路由级的缓存，无需额外配置。
-```ts
-import { PreRender } from '@modern-js/runtime/ssr';
-```
-:::
-
-## API
-
-`PreRender` 组件提供了一套常用的配置参数，用于控制缓存的规则、过期时间、缓存算法等。
-
-```tsx
-<PreRender></PreRender>
-```
-
-### 参数
-
-- interval：`number`，设置缓存保持新鲜的时间，单位秒。在该时间内，将直接使用缓存，并且不做异步渲染。
-- [staleLimit]：`number`，设置缓存完全过期的时间，单位秒。在该时间内，缓存可以被返回，否则必须使用重新渲染的结果。
-- [level]：`number`，设置缓存标识的计算规则等级，通常配合 `includes` 与 `matches` 使用。默认值为 `0`。
-
-```bash
-0：路由路径
-1：路由路径 + 查询字符串
-2：路由路径 + 请求头
-3：路由路径 + 查询字符串 + 请求头
-```
-
-- [includes]：`{ header?: string[], query?: string[] }`，设置需要被纳入缓存标识的内容，在 level 非 0 时使用。默认值为 `null`。
-- [matches]：`{ header?: Record<string, any>, query?: Record<string, any> }`，设置 query 或 header 的值在缓存标识计算中的重写规则，通常用在缓存分类时，支持正则表达式。默认值为 `null`。
-
-## 示例
-
-```tsx
-import { PreRender } from '@modern-js/runtime/ssr';
-
-export default function App() {
-  return (
-    <>
-        <PreRender interval={10} />
-        <div>Hello Modern</div>
-    </>
-  )
-}
-```
-
-下面例子展示了如何将 query、header 中指定的参数纳入缓存计算中：
-
-```tsx
-/* 使用 query 中的 channel 和 header 中的 language 计算缓存标识 */
-<PreRender interval={10} level={2} includes={{
-    query: ["channel"],
-    header: ["language"]
-}} />
-```
-
-下面例子展示了如何不让测试频道影响线上缓存：
-
-```tsx
-/* 将 query 中 channel 值为 test_ 开头的重写为 testChannel，否则重写为 otherChannel */
-<PreRender interval={10} level={2} includes={{
-    query: ["channel"],
-    header: ["language"]
-}} matches={{
-    query: {
-        channel: {
-            "testChannel", "^test_",
-            "otherChannel", ".*"
-        }
-    }
-}} />
-```

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

@@ -1,60 +0,0 @@
----
-title: useModuleApp
-sidebar_position: 6
----
-
-:::info 补充信息
-返回一个自动切换微前端路由的组件，默认激活的路由是配置里的 `activeWhen`。
-```ts
-import { useModuleApp } from '@modern-js/runtime';
-```
-:::
-
-:::caution 注意
-该 API 在微前端主应用中使用，需要先开启微前端。
-:::
-
-## API
-
-`useModuleApp() => React.FC<any>`
-
-返回子应用的 React 组件。
-
-## 示例
-
-需要先配置微前端子应用信息。
-
-```js title=modern.config.js
-defineConfig({
-  runtime: {
-    masterApp: {
-      manifest: {
-        modules: [
-          {
-            name: 'Home',
-            entry: 'http://www.home.com',
-            activeWhen: '/home'
-          },
-          {
-            name: 'Contact',
-            entry: 'http://www.contact.com',
-            activeWhen: '/contact'
-          },
-        ]
-      }
-    }
-  }
-})
-```
-
-```ts title=App.tsx
-import { useModuleApp } from '@modern-js/runtime';
-
-function App() {
-  const MApp = useModuleApp();
-
-  return <MApp />;
-}
-```
-
-通过 `useModuleApp()` 获取到 `MApp` 组件，渲染 MApp 组件，将会根据配置中的 `activeWhen` 作为激活路由加载对应的子应用。

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

@@ -1,64 +0,0 @@
----
-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

@@ -1,39 +0,0 @@
----
-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

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

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

@@ -1,35 +0,0 @@
-# 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

@@ -1,120 +0,0 @@
----
-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

@@ -1,70 +0,0 @@
----
-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

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

package/zh/apis/app/runtime/container/use-loader.md

@@ -1,64 +0,0 @@
----
-title: useLoader
-sidebar_position: 2
----
-
-:::info 补充信息
-一个同构的 API，通常会用来做异步请求。当 SSR 的时候，服务端使用 `useLoader` 预加载数据，同时浏览器端也会复用这部分数据。
-
-```ts
-import { useLoader } from "@modern-js/runtime";
-```
-
-:::
-
-## API
-
-`useLoader(loaderFn,[options]) => object`
-
-### 参数
-
-- loaderFn: `(context: any, params: Record<string, any>) => Promise`，用于加载数据的函数，返回 Promise。
-- [options]: `object` ，可选配置项。
-  - [onSuccess]: `(data: Record<string, any>) => void`，`loaderFn` 执行成功的回调。
-  - [onError]: `(error: Error) => void`，`loaderFn` 执行失败的回调。
-  - [initialData]: `Record<string, any>`， `loaderFn` 首次执行前的初始数据，对应返回值中的 `data` 字段。
-  - [skip]: `boolean`，当值为 `true` 时， `loaderFn` 不执行。
-  - [params]: `Record<string, any>`， 当 `params` 序列化结果发生改变时，`loaderFn` 会重新执行。同时，`params` 也会作为 `loaderFn` 的第二个参数被传入。
-  - [static]: `boolean`，当值为 `true` 时，`useLoader` 用于 [SSG](/docs/guides/advanced-features/ssg) 编译阶段数据的获取。
-
-### 返回值
-
-- data: `Record<string, any>`， `loaderFn` 函数执行成功时的返回数据。
-- loading: `boolean`，表示 `loaderFn` 是否处于执行过程中。
-- error: `Error`，`loaderFn` 函数执行失败时的错误信息。
-- reload: `(params?: Params) => Promise<any> | undefined`，调用该函数可以重新执行 `loaderFn`。
-  - params?: `Record<string, any> | undefined`，当 `params` 为 `undefined`，`loaderFn` 执行时将复用上次的 `params` 参数；当 `params` 有值时，则会使用新的 `params` 参数重新执行 `loaderFn`。
-- reloading: `boolean`，调用 `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/utility/loadable/_category_.json

@@ -1,4 +0,0 @@
-{
-  "label": "loadable",
-  "position": 9
-}

package/zh/apis/app/runtime/utility/loadable/lazy.md

@@ -1,29 +0,0 @@
----
-title: lazy
-sidebar_position: 2
----
-
-:::info
-用于创建支持 [Suspense](https://reactjs.org/docs/react-api.html#reactsuspense) 的 `loadable 组件`。
-```ts
-import { lazy } from '@modern-js/runtime/loadable';
-```
-:::
-## API
-
-### lazy
-
-```ts
-import { lazy } from '@modern-js/runtime/loadable';
-const OtherComponent = lazy(() => import('./OtherComponent'));
-```
-
-### lazy.lib
-
-创建一个支持 [Suspense](https://reactjs.org/docs/react-api.html#reactsuspense) 的 `loadable 库`。
-
-```ts
-import { lazy } from '@modern-js/runtime/loadable';
-const Moment = lazy.lib(() => import('moment'))
-```
-

package/zh/apis/app/runtime/utility/loadable/loadable-component.md

@@ -1,61 +0,0 @@
----
-title: LoadableComponent
-sidebar_position: 3
----
-
-`LoadableComponent` 是 `loadable` 或 `lazy` 函数返回的对象类型。
-
-## LoadableComponent 类型
-
-```ts
-type LoadableComponent<Props> =
-  React.ComponentType<
-    Props & { fallback?: JSX.Element; }>
-  & {
-    preload(props?: Props): void;
-    load(props?: Props): Promise<React.ComponentType<Props>>;
-  }
-```
-
-### props
-
-类型：`object`
-
-`LoadableComponent` 组件可接收任意 props 参数，这些参数会转发给 loadFn。
-
-### fallback
-
-类型：`JSX.Element`
-
-当组件尚未加载完成（即 loading 阶段）会显示 `fallback` 内容。
-
-## LoadableComponent.preload
-
-```ts
-import loadable from '@modern-js/runtime/loadable'
-
-const OtherComponent = loadable(() => import('./OtherComponent'))
-OtherComponent.preload()
-```
-
-`preload` 接收的参数会全部传给 `loadFn`。
-
-:::info 注
-预加载脚本中函数始终不会返回一个 Promise 对象，如果你想等待组件加载完成，请使用 [load](#LoadableComponent.load) 函数
-:::
-
-
-## LoadableComponent.load
-
-```ts
-import loadable from '@modern-js/runtime/loadable'
-
-const OtherComponent = loadable(() => import('./OtherComponent'))
-OtherComponent.load().then(() => {
-  console.log('Component is loaded!')
-})
-```
-
-:::info 注
-如果你无需等待组件加载完成，则使用 [preload](#LoadableComponent.preload) 即可。
-:::