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

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

@@ -0,0 +1,96 @@
+---
+title: PreRender
+---
+# 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.mdx

@@ -0,0 +1,35 @@
+---
+title: act
+---
+# 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.mdx

@@ -0,0 +1,40 @@
+---
+title: cleanup
+sidebar_position: 3
+---
+# cleanup
+
+用于卸载掉当前已渲染的所有组件。
+
+## 使用姿势
+
+```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.mdx

@@ -0,0 +1,71 @@
+---
+title: render
+---
+# 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.mdx

@@ -0,0 +1,32 @@
+---
+title: renderApp
+---
+# 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.mdx

@@ -0,0 +1,43 @@
+---
+title: CSS-In-JS API
+---
+# 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.mdx

@@ -0,0 +1,38 @@
+---
+title: Head
+---
+# 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.mdx

@@ -0,0 +1,83 @@
+---
+title: loadable
+---
+# 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.mdx

@@ -0,0 +1,134 @@
+---
+title: Hook
+---
+# Hook
+
+用于拓展 Modern.js 内置的 Web Server，非 BFF 请求会经过这些中 Hook 的处理。
+
+:::note
+更多内容可以查看[自定义 Web Server](/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.mdx

@@ -0,0 +1,111 @@
+---
+title: Middleware
+---
+# Middleware
+
+用于拓展 Modern.js 内置的 Web Server，只有 SSR 请求会经过这些中间件。
+
+与 [Hook](/apis/app/runtime/web-server/hook) 不同的是，Middleware 可以使用 Server 运行时框架拓展。
+
+:::note
+更多内容可以查看[自定义 Web Server](/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();
+});
+```