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

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

@@ -1,89 +0,0 @@
----
-title: routes/
-sidebar_position: 2
----
-
-应用使用基于文件系统路由时的入口标识。
-
-当项目结构为 `Routes 入口` 类型时， 会分析 `src/routes` 目录下的文件得到客户端路由配置。具体用法请查看[约定式路由](/docs/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](/docs/apis/app/runtime/router/#useparams) 获取对应命名的参数。
-
-在 loader 中，params 会作为 [loader](/docs/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.md

@@ -1,31 +0,0 @@
----
-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/hooks/src/stories.md

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

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

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

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

@@ -1,61 +0,0 @@
----
-sidebar_position: 1
-title: defineConfig
----
-
-用于动态配置应用。
-
-## 使用姿势
-
-```ts
-import { defineConfig } from '@modern-js/runtime';
-```
-
-Runtime 配置通常可以在 `modern.config.js` 的 `runtime` 空间下配置，如 [router](/docs/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](/docs/configure/app/runtime/state)、[runtime.router](/docs/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.md

@@ -1,43 +0,0 @@
----
-title: 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.md

@@ -1,36 +0,0 @@
----
-title: 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.md

@@ -1,68 +0,0 @@
----
-title: bootstrap
----
-
-用于启动和挂载应用，通常情况下不做手动调用。只有在使用[自定义 App](/docs/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.md

@@ -1,30 +0,0 @@
----
-title: createApp
----
-
-用于创建自定义入口，定制运行时插件。只有在使用[自定义 App](/docs/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.md

@@ -1,83 +0,0 @@
----
-title: 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](/docs/apis/app/runtime/core/use-runtime-context)。
-:::
-
-### 参数
-
-- `loaderFn`：用于加载数据的函数，返回 Promise。
-- `options`：可选配置项。
-  - `onSuccess`：执行成功的回调。
-  - `onError`：执行失败的回调。
-  - `initialData`：首次执行前的初始数据，对应返回值中的 `data` 字段。
-  - `skip`：当值为 `true` 时，函数不执行。
-  - `params`：当 `params` 序列化结果发生改变时，函数会重新执行。同时，`params` 也会作为函数的第二个参数被传入。
-  - `static`：当值为 `true` 时，`useLoader` 用于 [SSG](/docs/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.md

@@ -1,134 +0,0 @@
----
-title: 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.md';
-
-<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.md';
-
-<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.md

@@ -1,59 +0,0 @@
----
-title: 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.md

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