@modern-js/main-doc 2.1.0 → 2.3.0

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,60 +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,67 +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,137 +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,58 +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/model/Provider.md

@@ -1,35 +0,0 @@
----
-sidebar_position: 8
-title: Provider
----
-
-import ReduckTip from '@site-docs/components/reduck-tip.md'
-
-<ReduckTip />
-
-`Provider` 是一个组件，它将 Reduck 的 Store 注入到应用的组件树中，使组件树内部的组件可以访问 Model。一般情况下，`Provider` 会定义在组件树的最顶层。
-
-## 函数签名
-
-```ts
-interface ProviderProps {
-  store?: ReduckStore;
-  config?: AppConfig;
-}
-```
-
-### 参数
-
-- store：[`createStore`](./create-store.md) 创建的 Store 对象。
-- config：创建 Reduck Store 的配置，同 [`createApp`](./create-app.md) 的 `config` 参数。
-
-## 示例
-
-```tsx title="应用入口文件"
-ReactDOM.render(
-  <Provider>
-    <App />
-  </Provider>,
-  document.getElementById('root'),
-);
-```

package/zh/apis/app/runtime/model/auto-actions.md

@@ -1,120 +0,0 @@
----
-sidebar_position: 6
-title: Auto actions
----
-
-import ReduckTip from '@site-docs/components/reduck-tip.md'
-
-<ReduckTip />
-
-Reduck 可以根据 State 的类型，自动生成相应的 Actions，为修改 State 提供便利。
-
-:::tip 提示
-可通过 [`runtime.state.autoActions`](/docs/configure/app/runtime/state#autoactions) 关闭 auto actions 功能。
-:::
-
-## 示例
-
-### 基础数据类型
-
-State 类型为 `string`、`number`、`boolean`、`null` 时，生成 `setState` Action。
-
-```tsx title="示例"
-const fooModel = model('foo').define({
-  state: 1,
-});
-
-function App() {
-  const [state, actions] = useModel(fooModel);
-
-  return (
-    <div>
-      <div>State: {state}</div>
-      <button
-        type="button"
-        onClick={() => {
-          // 调用自动生成的 setState Action
-          actions.setState(state + 1);
-        }}
-      >
-        add
-      </button>
-    </div>
-  );
-}
-```
-
-### 数组 Array
-
-State 类型为 Array 时，生成下列 Actions：
-
-- `push`：将一个或多个元素添加到数组的末尾。
-- `pop`：从数组中删除最后一个元素。
-- `shift`：从数组中删除第一个元素。
-- `unshift`：将一个或多个元素添加到数组的开头。
-  - 语法：`arr.unshift(element1, ..., elementN)`
-  - `elementN`：要添加到数组开头的元素或多个元素。
-- `filter`：过滤元素。
-<!-- 语义与原生方法不同，待修改 API -->
-- `concat`：拼接数组。
-<!-- 语义与原生方法不同，待修改 API -->
-- `splice`：通过删除或替换现有元素或者原地添加新的元素来修改数组，并以数组形式返回修改后的数组（注意和原生 `splice` 返回值不同）。
-  - 语法：`splice(start[, deleteCount[, item1[, item2[, ...]]]])`
-  - `start`：指定修改的开始位置（从 0 计数）。
-  - `deleteCount`：可选，整数，表示要移除的数组元素的个数。
-  - `item, item2, ...`：可选，要添加进数组的元素，从 start 位置开始。如果不指定，则 `splice` 将只删除数组元素。
-
-```tsx title="示例"
-const fooModel = model('foo').define({
-  state: [1, 2, 3],
-});
-
-function App() {
-  const [state, actions] = useModel(fooModel);
-
-  useEffect(() => {
-    actions.push(4);
-    actions.pop();
-    actions.shift(0);
-    actions.unshift();
-    actions.filter(val => val <= 2);
-    actions.splice(0, 1, 1, 2);
-  }, []);
-
-  return (
-    <div>
-      <div>State: {state}</div>
-    </div>
-  );
-}
-```
-
-### 简单对象 PlainObject
-
-State 类型为 PlainObject 时，根据 State 包含的属性名，生成 `set${key}`（小驼峰命名）Actions。
-
-```tsx title="示例"
-const fooModel = model('foo').define({
-  state: {
-    a: 1,
-    b: { value: 1 },
-    c: 'c',
-  },
-});
-
-function App() {
-  const [state, actions] = useModel(fooModel);
-
-  useEffect(() => {
-    actions.setA(2);
-    actions.setB({ value: 2 });
-    actions.setC('d');
-  }, []);
-
-  return (
-    <div>
-      <div>State: {state}</div>
-    </div>
-  );
-}
-```