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

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

@@ -1,91 +0,0 @@
----
-title: PreRender
----
-
-无展示内容的高阶组件，通过类似 Helmet 的方式实现 SPA 路由级的缓存，无需额外配置。
-
-## 使用姿势
-
-```tsx
-import { PreRender } from '@modern-js/runtime/ssr';
-
-export default () => (
-  <>
-    <PreRender interval={5} />
-  </>
-)
-```
-
-## 函数签名
-
-`PreRender` 组件提供了一套常用的配置参数，用于控制缓存的规则、过期时间、缓存算法等。
-
-```tsx
-type Props {
-  interval: number;
-  staleLimit: number;
-  level: number;
-  include: { header?: string[], query?: string[] };
-  matches: { header?: Record<string, any>, query?: Record<string, any> }
-}
-
-function PreRender(props: Props): React.Component
-```
-
-### 参数
-
-- `interval`：设置缓存保持新鲜的时间，单位秒。在该时间内，将直接使用缓存，并且不做异步渲染。
-- `staleLimit`：设置缓存完全过期的时间，单位秒。在该时间内，缓存可以被返回，并且会做一步渲染，否则必须使用重新渲染的结果。
-- `level`：设置缓存标识的计算规则等级，通常配合 `includes` 与 `matches` 使用。默认值为 `0`。
-
-```bash
-0：路由路径
-1：路由路径 + 查询字符串
-2：路由路径 + 请求头
-3：路由路径 + 查询字符串 + 请求头
-```
-
-- `includes`：设置需要被纳入缓存标识的内容，在 level 非 0 时使用。默认值为 `null`。
-- `matches`：设置 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/testing/act.md

@@ -1,34 +0,0 @@
----
-title: act
----
-
-用于确保渲染、事件、数据获取等行为已经应用在 DOM 上。
-
-## 使用姿势
-
-```ts
-import { act } from '@modern-js/runtime/testing';
-```
-
-## 函数签名
-
-`act` 和 [react-dom/test-utils act 函数](https://reactjs.org/docs/testing-recipes.html#act) 是一致的。
-
-## 示例
-
-```tsx
-import ReactDOM from 'react-dom';
-import { act } from '@modern-js/runtime/testing';
-import { Foo } from '@/components/Foo';
-
-describe('test act', () => {
-  it('it should be foo', () => {
-    const el = document.createElement('div');
-    act(() => {
-      ReactDOM.render(<Foo />, el);
-    });
-
-    expect(el.innerHTML).toBe('<div>Foo</div>');
-  });
-});
-```

package/zh/apis/app/runtime/testing/cleanup.md

@@ -1,38 +0,0 @@
----
-title: cleanup
-sidebar_position: 3
----
-
-用于卸载掉当前已渲染的所有组件。
-
-## 使用姿势
-
-```ts
-import { cleanup } from '@modenr-js/runtime/testing';
-```
-
-## 函数签名
-
-`function cleanup(): void`
-
-## 示例
-
-:::info 注
-请注意，如果你使用的测试框架支持 afterEach，并且它被注入到你的测试环境中（如mocha、Jest和Jasmine），**会默认在 afterEach 钩子里执行 `cleanup`**。否则，你将需要在每次测试后进行手动清理。
-:::
-
-例如，如果你使用[ava](https://github.com/avajs/ava)测试框架，那么你需要像这样使用test.afterEach钩子。
-
-```tsx
-import { cleanup, render } from '@modern-js/runtime/testing';
-import test from 'ava';
-
-test.afterEach(cleanup);
-
-test('renders into document', () => {
-  render(<div />);
-  // ...
-});
-
-// ... more tests ...
-```

package/zh/apis/app/runtime/testing/render.md

@@ -1,72 +0,0 @@
----
-title: render
----
-
-用于在测试用例中渲染组件，完成测试。
-
-## 使用姿势
-
-```ts
-import { render } from '@modern-js/runtime/testing';
-```
-
-## 函数签名
-
-```ts
-type Options = {
-  container: DOMElement;
-  baseElement: DOMElement;
-  hydrate: boolean;
-  warpper: React.ComponentType<{children: ReactNode}>;
-  queries: any;
-};
-
-type RenderResult = {
-  {...queries}: any;
-  container: DOMElement;
-  baseElement: DOMElement;
-  debug: function;
-  rerender: function;
-  unmount: function;
-  asFragment: function;
-}
-
-function render(ui: React.ReactElement<any>, options: Options): RenderResult;
-```
-
-### 参数
-
-- `ui`：需要被渲染的 React 组件。
-- `options`：render 可选配置。
-  - `container`：表示组件所要挂载到的 DOM 节点，默认是会创建一个 `div` 元素，并自动添加到 `document.body` 上。这个 `div` 元素就是组件要挂载的节点。默认值是 `document.body.append(document.createElement('div'))`。
-  - `baseElement`：用于指定 `queries` 中使用到的 `basename`。如果指定了 `container`, 则默认值为 `container` 的值，否则就是 `document.body`。
-  - `hydrate`：如果设置为 `true`，则会使用 [ReactDOM.hydrate](https://reactjs.org/docs/react-dom.html#hydrate) 渲染组件。默认值为 `false`。
-  - `wrapper`：是一个 react 组件，可用于自定义渲染逻辑。
-  - `queries`：自定义一些自己的 `queries`。
-
-
-### 返回值
-
-- `{...queries}`：所有可用的 [queries](https://testing-library.com/docs/queries/about/)。
-- `container`：挂载 React 组件的 DOM 节点。
-- `baseElement`
-- `debug`
-- `rerender`：如果想测试一个已渲染的组件在其 props 更新时的一些场景，可以使用 rerender 来现实。
-- `unmount`：会卸载掉已渲染的组件。如果想测试组件卸载后的情况（如，绑定的事件是否在 unmount 阶段被卸载掉），那么这个 API 是很帮助的。
-- `asFragment`：返回当前渲染的组件的 [DocumentFragment](https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment) 对象。可用于测试 react 事件触发后 DOM 结构的响应。
-
-
-## 示例
-
-```ts
-import { render } from '@modern-js/runtime/testing';
-import App from './App';
-
-test('renders a message', () => {
-  const { container, getByText } = render(<App />);
-  expect(getByText('Hello, world!')).toBeInTheDocument();
-  expect(container.firstChild).toMatchInlineSnapshot(`
-    <h1>Hello, World!</h1>
-  `);
-});
-```

package/zh/apis/app/runtime/testing/renderApp.md

@@ -1,31 +0,0 @@
----
-title: renderApp
----
-
-`render` 函数用于测试普通组件，`renderApp` 函数用于测试应用组件。
-
-## 使用姿势
-
-```ts
-import { renderApp } from '@modern-js/runtime/testing';
-```
-
-应用组件指包含一些 Modern.js 上下文的组件，如 App 根组件，使用了 Model 的 Container 等。对于这类组件的测试，可以使用 `renderApp` 函数，会自动按照当前 `modern.config.js` 配置，包裹上对应的上下文信息。
-
-## 函数签名
-
-`renderApp` 和 [render](./render.md) 完全一致。
-
-## 示例
-
-```ts
-import { renderApp } from '@modern-js/runtime/testing';
-import App from './App';
-
-describe('test', () => {
-  it('test App', () => {
-    const { getByText } = renderApp(<App />);
-    expect(getByText('Hello Modern!')).toBeInTheDocument();
-  });
-});
-```

package/zh/apis/app/runtime/utility/css-in-js.md

@@ -1,42 +0,0 @@
----
-title: CSS-In-JS API
----
-
-使用 Style Component 来编写组件 CSS。
-
-## 使用姿势
-
-```ts
-import styled from '@modern-js/runtime/styled';
-```
-
-## 函数签名
-
-请看 [styled-component API](https://styled-components.com/docs/api)。
-
-## 示例
-
-```tsx
-import styled from '@modern-js/runtime/styled';
-
-const Button = styled.button`
-  background: palevioletred;
-  border-radius: 3px;
-  border: none;
-  color: white;
-`;
-
-const TomatoButton = styled(Button)`
-  background: tomato;
-`;
-
-function ButtonExample(){
-  return (
-    <>
-      <Button>I'm purple.</Button>
-      <br />
-      <TomatoButton>I'm red.</TomatoButton>
-    </>
-  );
-};
-```

package/zh/apis/app/runtime/utility/head.md

@@ -1,39 +0,0 @@
----
-title: Head
----
-
-用于给 `<head>` 元素内添加 html 元素（如 title、meta、script 等），支持 `SSR`。
-
-## 使用姿势
-
-```tsx
-import { Helmet } from '@modern-js/runtime/head';
-
-export default () => (
-  <Helmet>...</Helmet>
-)
-```
-
-## 示例
-
-```tsx
-import { Helmet } from '@modern-js/runtime/head';
-
-function IndexPage() {
-  return (
-    <div>
-      <Helmet>
-        <title>My page title</title>
-        <meta name="viewport" content="initial-scale=1.0, width=device-width" />
-      </Helmet>
-      <p>Hello Modern.js!</p>
-    </div>
-  )
-}
-
-export default IndexPage
-```
-
-## 更多用法
-
-详见 [react-helmet](https://github.com/nfl/react-helmet)。

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

@@ -1,83 +0,0 @@
----
-title: loadable
----
-
-用于创建 Loadable 的组件。
-
-## 使用姿势
-
-```ts
-import loadable from '@modern-js/runtime/loadable';
-```
-
-## 函数签名
-
-```ts
-type Options = {
-  resolveComponent?: (
-    module: Module,
-    props: Props,
-  ) => React.ComponentType<Props>,
-  fallback?: JSX.Element;
-  ssr?: boolean;
-}
-
-function loadable(loadFn: Function, options?: Options) => LoadableComponent
-```
-
-### 参数
-
-#### loadFn
-
-用于加载组件。
-
-```ts
-import loadable from '@modern-js/runtime/loadable';
-
-const OtherComponent = loadable(() => import('./OtherComponent'))
-```
-
-#### options.resolveComponent
-
-类型：`(module: Module, props: Props) => React.ComponentType<Props>`
-
-`module` 为 `loadFn` 返回的组件，`props` 是 loadable 返回的组件接受的 props 参数。默认的话，我们认为 `import` 的文件都是默认导出 react 组件，这时候直接渲染该组件即可。但当组件是具名导出的，或者我们需要根据具体的 `props` 动态判断需要渲染哪个组件的时候，可以使用 `resolveComponent` 来实现。下面是一个示例：
-
-```ts title='component.js'
-export const Apple = () => 'Apple!'
-export const Orange = () => 'Orange!'
-```
-
-```ts title='loadable.js'
-const LoadableApple = loadable(() => import('./components'), {
-  resolveComponent: (components) => components.Apple,
-})
-const LoadableOrange = loadable(() => import('./components'), {
-  resolveComponent: (components) => components.Orange,
-})
-const LoadableFruit = loadable(() => import('./components'), {
-  resolveComponent: (components, props) => components[props.fruit],
-})
-```
-
-#### options.fallback
-
-是否在 loading 阶段显示 fallback 内容。
-
-#### options.ssr
-
-是否支持 SSR，默认值是 `true`。
-
-### 返回值
-
-#### LoadableComponent
-
-```ts
-type LoadableComponent<Props> =
-  React.ComponentType<
-    Props & { fallback?: JSX.Element; }>
-  & {
-    preload(props?: Props): void;
-    load(props?: Props): Promise<React.ComponentType<Props>>;
-  }
-```

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

@@ -1,131 +0,0 @@
----
-title: Hook
----
-
-用于拓展 Modern.js 内置的 Web Server，非 BFF 请求会经过这些中 Hook 的处理。
-
-:::note
-更多内容可以查看[自定义 Web Server](/docs/guides/advanced-features/web-server)。
-:::
-
-## 使用姿势
-
-```ts
-import { AfterMatchHook, AfterRenderHook } from '@modern-js/runtime/server';
-
-export const afterMatch: AfterMatchHook = (context, next) => {}
-export const afterRender: AfterRenderHook = (context, next) => {}
-```
-
-:::info 自定义 Web Server
-使用该 API 前，请先执行 `pnpm run new` 新建「自定义 Web Serve」源码目录。
-
-```bash
-pnpm run new
-? 请选择你想要的操作 创建工程元素
-? 新建「自定义 Web Server」源码目录
-```
-:::
-
-## 函数签名
-
-```ts
-type HookContext = {
-  response: {
-    set: (key: string, value: string) => void;
-    status: (code: number) => void;
-    cookies: {
-      get: (key: string) => string;
-      set: (key: string, value: string) => void;
-      delete: () => void;
-      clear: () => void;
-    };
-    raw: (
-      body: string,
-      { status, headers }: { status: number; headers: Record<string, any> },
-    ) => void;
-  };
-  request: {
-    url: string;
-    host: string;
-    pathname: string;
-    query: Record<string, any>;
-    cookie: string;
-    cookies: {
-      get: (key: string) => string;
-    };
-    headers: IncomingHttpHeaders;
-  };
-};
-
-function Hook(context: HookContext, next: NextFunction): Promsie<void> | void;
-```
-
-另外，不同 Hook 额外提供了不同的上下文。目前 Modern.js 支持 `AtferMatch` 和 `AfterRender` 两个 Hook。
-
-```ts
-type AfterMatchContext = HookContext & {
-  router: {
-    redirect: (url: string, status: number) => void;
-    rewrite: (entry: string) => void;
-  };
-}
-
-type AfterRenderContext = {
-  template: {
-    get: () => string;
-    set: (html: string) => void;
-    prependHead: (fragment: string) => void;
-    appendHead: (fragment: string) => void;
-    prependBody: (fragment: string) => void;
-    appendBody: (fragment: string) => void;
-  };
-};
-```
-
-### 参数
-
-- `context`：提供当前 Hook 上下文。
-  - `response`：提供一系列处理响应的操作
-  - `request`：提供一系列获取请求信息的操作
-  - `router`：提供对响应路由的快捷操作
-  - `template`：提供对响应内容的快捷操作
-- `next`：执行当前 Hook 的下一个监听函数（不影响整体服务端流程）。
-
-## 示例
-
-### Redirect
-
-将页面重定向到站点外的页面，例如跳转到统一登录页：
-
-```ts
-import type { AfterMatch } from '@modern-js/runtime/server';
-
-export const afterMatch: AfterMatch = async (ctx, next) => {
-  ctx.router.redirect('https://website.com/login', 302);
-};
-```
-
-### Rewrite
-
-将页面重写到当前站点的其他页面，例如同一个路由根据 UA 返回适配不同端的页面：
-
-```ts
-import type { AfterMatch } from '@modern-js/runtime/server';
-
-export const afterMatch: AfterMatch = async (ctx, next) => {
-  ctx.router.rewrite('mobile');
-};
-```
-
-### HTML 内容注入
-
-为页面注入某些与渲染主体无关的 HTML 内容，如脚本、页面骨架等：
-
-```ts
-import type { AfterRender } from '@modern-js/runtime/server';
-
-export const afterRender: AfterRenderHook = (context, next) => {
-  ctx.template.prependBody('<div>Footer</div>');
-}
-```

package/zh/apis/app/runtime/web-server/middleware.md

@@ -1,107 +0,0 @@
----
-title: Middleware
----
-
-用于拓展 Modern.js 内置的 Web Server，只有 SSR 请求会经过这些中间件。
-
-与 [Hook](/docs/apis/app/runtime/web-server/hook) 不同的是，Middleware 可以使用 Server 运行时框架拓展。
-
-:::note
-更多内容可以查看[自定义 Web Server](/docs/guides/advanced-features/web-server)。
-:::
-
-## 使用姿势
-
-```ts
-import { Middleware } from '@modern-js/runtime/server';
-
-export const middleware: Middleware = async (context, next) => {}
-export const middleware: Middleware[] = [
-  async (context, next) => {},
-  async (context, next) => {},
-]
-```
-
-:::info 自定义 Web Server
-使用该 API 前，请先执行 `pnpm run new` 新建「自定义 Web Server」源码目录。
-
-```bash
-pnpm run new
-? 请选择你想要的操作 创建工程元素
-? 新建「自定义 Web Server」源码目录
-```
-:::
-
-## 函数签名
-
-```ts
-type MiddlewareContext = {
-  response: {
-    set: (key: string, value: string) => void;
-    status: (code: number) => void;
-    cookies: {
-      get: (key: string) => string;
-      set: (key: string, value: string) => void;
-      delete: () => void;
-      clear: () => void;
-      apply: () => void;
-    };
-    raw: (
-      body: string,
-      { status, headers }: { status: number; headers: Record<string, any> },
-    ) => void;
-    locals: Record<string, any>;
-  };
-  request: {
-    url: string;
-    host: string;
-    pathname: string;
-    query: Record<string, any>;
-    cookie: string;
-    cookies: {
-      get: (key: string) => string;
-    };
-    headers: IncomingHttpHeaders;
-  };
-  source: {
-    req: IncomingMessage;
-    res: ServerResponse;
-  };
-};
-
-type RequestHandler = (context: Context, next: NextFunction) => Promise<void> | void;
-```
-
-
-### 参数
-
-- `context`：提供当前 Hook 上下文。
-  - `response`：提供一系列处理响应的操作
-  - `request`：提供一系列获取请求信息的操作
-  - `source`：提供 Node.js 原生的 `req` 与 `res` 对象。
-- `next`：执行当前 Hook 的下一个监听函数（不影响整体服务端流程）。
-
-## 示例
-
-### 服务端耗时打点
-
-```ts
-export const Middleware = () => async (ctx, next) => {
-  const start = Date.now();
-  ctx.res.once('finish', () => {
-    console.log(Date.now() - start);
-  });
-}
-```
-
-### 注入服务端工具 & 数据
-
-Modern.js 提供了 `res.locals` 属性用来存放当前请求的局部变量。
-
-```ts
-export const Middleware = () => async (ctx, next) => {
-  ctx.res.locals.id = 'Modern.js';
-  ctx.res.locals.rpc = createRpcInstance();
-});
-```
-