@modern-js/main-doc 2.69.5 → 3.0.0-alpha.0

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

@@ -1,96 +0,0 @@
----
-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/docs/zh/apis/app/runtime/web-server/hook.mdx

@@ -1,136 +0,0 @@
----
-title: Hook
----
-
-# Hook
-
-:::warning
-
-Hook API 已废弃，请使用[新版自定义 Web Server](/guides/advanced-features/web-server) 来处理页面请求。
-
-:::
-
-用于拓展 Modern.js 内置的 Web Server，所有的页面请求都会经过 Hook。
-
-
-## 使用姿势
-
-```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;
-    getStatus: () => number;
-    cookies: {
-      set: (key: string, value: string, options?: any) => 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 支持 `AfterMatch` 和 `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/docs/zh/apis/app/runtime/web-server/middleware.mdx

@@ -1,114 +0,0 @@
----
-title: Middleware
----
-
-# Middleware
-
-:::warning
-
-Middleware 已废弃，请使用[新版自定义 Web Server](/guides/advanced-features/web-server) 来处理页面请求。
-
-:::
-
-用于拓展 Modern.js 内置的 Web Server，与 [Hook](/apis/app/runtime/web-server/hook) 不同的是，Middleware 可以直接操作 Node 原生的请求、响应对象，并且可以使用框架拓展。
-
-
-## 使用姿势
-
-```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 Middleware = (
-  context: MiddlewareContext,
-  next: NextFunction,
-) => Promise<void> | void;
-
-type MiddlewareContext = {
-  response: {
-    set: (key: string, value: string) => void;
-    status: (code: number) => void;
-    getStatus: () => number;
-    cookies: {
-      set: (key: string, value: string, options?: any) => void;
-      clear: () => 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;
-  };
-};
-```
-
-### 参数
-
-- `context`：提供当前 Hook 上下文。
-  - `response`：提供一系列处理响应的操作
-  - `request`：提供一系列获取请求信息的操作
-  - `source`：提供 Node.js 原生的 `req` 与 `res` 对象。
-- `next`：执行当前 Hook 的下一个监听函数（不影响整体服务端流程）。
-
-:::warning
-`next` 函数的执行不影响后续内置流程，只控制下一个中间件是否执行。只有当响应被写入时，后续渲染流程才会中断。
-:::
-
-## 示例
-
-### 服务端耗时打点
-
-```ts
-export const Middleware = () => async (ctx, next) => {
-  const start = Date.now();
-  ctx.source.res.once('finish', () => {
-    console.log(Date.now() - start);
-  });
-};
-```
-
-### 注入服务端工具 & 数据
-
-Modern.js 提供了 `response.locals` 属性用来存放当前请求的局部变量。
-
-```ts
-export const Middleware = () => async (ctx, next) => {
-  ctx.response.locals.id = 'Modern.js';
-  ctx.response.locals.rpc = createRpcInstance();
-};
-```

package/docs/zh/apis/app/runtime/web-server/unstable_middleware.mdx

@@ -1,165 +0,0 @@
----
-title: Unstable Middleware
----
-
-# Unstable Middleware
-
-:::warning
-
-Unstable Middleware 已废弃，请使用[新版自定义 Web Server](/guides/advanced-features/web-server) 来处理页面请求。
-
-:::
-
-用于拓展 Modern.js 内置的 Web Server。 未来 UnstableMiddleware 将替代 [Middleware](/apis/app/runtime/web-server/middleware)
-
-## 使用
-
-```ts title="server/index.ts"
-import { UnstableMiddleware } from '@modern-js/runtime/server';
-
-export const unstableMiddleware: UnstableMiddleware[] = [];
-```
-
-## 类型
-
-**UnstableMiddleware**
-
-```ts
-type UnstableMiddleware<
-  V extends Record<string, unknown> = Record<string, unknown>,
-> = (
-  c: UnstableMiddlewareContext<V>,
-  next: UnstableNext,
-) => Promise<void | Response>;
-```
-
-**UnstableMiddlewareContext**
-
-```ts
-type Body = ReadableStream | ArrayBuffer | string | null;
-
-type UnstableMiddlewareContext<
-  V extends Record<string, unknown> = Record<string, unknown>,
-> = {
-  request: Request;
-  response: Response;
-  get: Get<V>;
-  set: Set<V>;
-  header: (name: string, value: string, options?: { append?: boolean }) => void;
-  status: (code: number) => void;
-  redirect: (location: string, status?: number) => Response;
-  body: (data: Body, init?: ResponseInit) => Response;
-  html: (
-    data: string | Promise<string>,
-    init?: ResponseInit,
-  ) => Response | Promise<Response>;
-};
-```
-
-**UnstableNext**
-
-```ts
-type UnstableNext = () => Promise<void>;
-```
-
-## 用例
-
-### web server 耗时打点
-
-```ts
-import { UnstableMiddleware } from '@modern-js/runtime/server';
-
-const time: UnstableMiddleware = async (c, next) => {
-  const start = Date.now();
-
-  await next();
-
-  const end = Date.now();
-
-  console.log(`${end - start}`);
-};
-
-export const unstableMiddleware: UnstableMiddleware[] = [time];
-```
-
-### 注入服务端数据，供页面 dataLoader 消费
-
-```ts title="shared/index.ts"
-export type Vars = {
-  message: string;
-};
-```
-
-```ts title="server/index.ts"
-import {
-  UnstableMiddleware,
-  UnstableMiddlewareContext,
-} from '@modern-js/runtime/server';
-import type { Vars } from '../shared/index';
-
-const setPayload: UnstableMiddleware<Vars> = async (
-  c: UnstableMiddlewareContext<Vars>,
-  next,
-) => {
-  c.set('message', 'facker');
-
-  await next();
-};
-
-export const unstableMiddleware: UnstableMiddleware<Vars>[] = [setPayload];
-```
-
-```ts title="src/routes/page.data.ts"
-import type { Payload } from '../../shared/index';
-import { LoaderFunctionArgs } from '@modern-js/runtime/router';
-
-export const loader = async ({ context }: LoaderFunctionArgs<Vars>) => {
-  const message = context?.get('message');
-
-  // ...
-};
-```
-
-### 重定向
-
-```ts
-import { UnstableMiddleware } from '@modern-js/runtime/server';
-
-const auth: UnstableMiddleware = async (c, next) => {
-  const user = getUser(c.request);
-
-  if (!user) {
-    return c.redirect('/login');
-  }
-
-  await next();
-};
-
-export const unstableMiddleware: UnstableMiddleware[] = [auth];
-```
-
-### 修改响应体
-
-```ts
-import { UnstableMiddleware } from '@modern-js/runtime/server';
-
-const modifier: UnstableMiddleware = async (c, next) => {
-  await next();
-
-  const { response } = c;
-
-  const text = await response.text();
-
-  const newText = text.replace('<html>', `<html lang="${language}">`);
-
-  const newheaders = response.headers;
-  newheaders.set('x-custom-value', 'modern');
-
-  c.response = c.body(newText, {
-    status: response.status,
-    headers: newheaders,
-  });
-};
-
-export const unstableMiddleware: UnstableMiddleware[] = [modifier];
-```

package/docs/zh/components/bff-proxy-path-rewrite.mdx

@@ -1,16 +0,0 @@
-这里还可以进行路径重写，如将发送到 `localhost:8080/api/topics` 的请求代理到 `https://cnodejs.org/api/v1/topics`。
-
-```ts title="modern.server-runtime.config.ts"
-import { defineConfig } from '@modern-js/app-tools/server';
-export default defineConfig({
-  bff: {
-    proxy: {
-      '/api': {
-        target: 'https://cnodejs.org',
-        pathRewrite: { '/api/topics': '/api/v1/topics' },
-        changeOrigin: true,
-      },
-    },
-  },
-});
-```

package/docs/zh/components/bff-proxy-principle.mdx

@@ -1 +0,0 @@
-BFF Proxy 使用了强大的 [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware)，如果需要更多高级的用法， 可以查看它的[文档](https://github.com/chimurai/http-proxy-middleware#options)。

package/docs/zh/components/builder.mdx

@@ -1,3 +0,0 @@
-Builder 指的是 Modern.js 的构建层，它的目标是为 Modern.js 用户提供开箱即用的构建能力，并支持在 webpack 和 Rspack 间无缝切换。
-
-Modern.js `MAJOR_VERSION.46.0` 之前版本使用的是 `@modern-js/builder`, 从 `MAJOR_VERSION.46.0` 开始升级为 [Rsbuild](https://rsbuild.rs/)。

package/docs/zh/components/create-bff-api-app.mdx

@@ -1,25 +0,0 @@
-
-1. 执行 `@modern-js/create` 命令：
-
-```bash
-npx @modern-js/create@latest myapi
-```
-
-2. 可交互的问答界面中，按照默认的选择进行初始化:
-
-```bash
-? 请选择开发语言 TS
-? 请选择包管理工具 pnpm
-```
-
-3. 执行 `new` 命令，启用 BFF:
-
-```bash
-? 请选择你想要的操作 启用可选功能
-? 请选择功能名称 启用「BFF」功能
-? 请选择 BFF 类型 框架模式
-```
-
-
-4. 执行【[已启用 BFF 的项目](/guides/advanced-features/bff/cross-project.html#已启用-bff-的项目)】步骤，即可打开跨项目调用开关。
-需要注意的是，当项目仅作为 BFF 生产端，其运行时不依赖 `/src` 源码目录。因此，移除 `/src` 目录可在一定程度上优化工程的编译效率。

package/docs/zh/components/custom-router-micro-frontend.mdx

@@ -1,40 +0,0 @@
-```js title="src/App.tsx"
-import { useModuleApps } from '@modern-js/plugin-garfish/runtime';
-
-import { RouterProvider, Route, createBrowserRouter, createRoutesFromElements, BrowserRouter, Link, Outlet } from '@modern-js/runtime/router';
-
-const AppLayout = () => (
-  <>
-    <div><Link to={'/table'}>加载约定式路由子应用</Link></div>
-    <div><Link to={'/dashboard'}>加载自控式路由子应用</Link></div>
-    <div><Link to={'/'}>卸载子应用</Link></div>
-    <Outlet />
-  </>
-)
-
-export default () => {
-  const { apps, MApp, Table, Dashboard } = useModuleApps();
-
-  // 使用的不是 MApp 组件，需要使用 createBrowserRouter 来创建路由
-  const router = createBrowserRouter(
-    createRoutesFromElements(
-      <Route path="/" element={<AppLayout />}>
-        <Route key={'table'} path={'table/*'} element={<Table />} />
-        <Route key={'dashboard'} path={'dashboard/*'} element={<Dashboard />} />
-      </Route>
-    )
-  );
-
-  return (
-    // 方法一：使用 MApp 自动根据配置的 activeWhen 参数加载子应用(本项目配置在 modern.config.ts 中)
-    // <BrowserRouter>
-    //   <MApp />
-    // </BrowserRouter>
-
-    // 方法二：手动写 Route 组件方式加载子应用，方便于需要鉴权等需要前置操作的场景
-    <>
-      <RouterProvider router={router} />
-    </>
-  );
-};
-```

package/docs/zh/components/enable-micro-frontend.mdx

@@ -1,30 +0,0 @@
-```ts title="modern.config.ts"
-import { appTools, defineConfig } from '@modern-js/app-tools';
-import { garfishPlugin } from '@modern-js/plugin-garfish';
-
-export default defineConfig({
-  runtime: {
-    router: true,
-  },
-  plugins: [appTools(), garfishPlugin()],
-});
-
-```
-
-```ts title="src/modern.runtime.ts"
-import { defineRuntimeConfig } from '@modern-js/runtime';
-
-export default defineRuntimeConfig({
-  masterApp: {
-    apps: [{
-      name: 'Table',
-      entry: 'http://localhost:8081',
-      // activeWhen: '/table'
-    }, {
-      name: 'Dashboard',
-      entry: 'http://localhost:8082'
-      // activeWhen: '/dashboard'
-    }]
-  },
-});
-```

package/docs/zh/components/enableSwc.mdx

@@ -1,17 +0,0 @@
-首先，你需要执行 `pnpm run new` 启用 SWC 编译：
-
-```bash
-? 请选择你想要的操作 启用可选功能
-? 请选择功能名称 启用「SWC 编译」
-```
-
-执行完成后，你只需在 `modern.config.ts` 文件中注册 Modern.js 的 SWC 插件，即可启用 SWC 编译和压缩能力。
-
-```ts title="modern.config.ts"
-import { appTools, defineConfig } from '@modern-js/app-tools';
-import { swcPlugin } from '@modern-js/plugin-swc';
-
-export default defineConfig({
-  plugins: [appTools(), swcPlugin()],
-});
-```