@modern-js/main-doc 2.69.7 → 3.0.0-alpha.1

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/default-mwa-generate.mdx

@@ -1,4 +0,0 @@
-```bash
-? 请选择开发语言：TS
-? 请选择包管理工具：pnpm
-```

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()],
-});
-```

package/docs/zh/components/global-proxy-config.mdx

@@ -1,85 +0,0 @@
-- **类型：** `string | Object`
-- **默认值：** `null`
-
-该选项用于在开发环境下启用基于 [whistle](https://wproxy.org/whistle/) 的全局代理，可以用来查看、修改 HTTP/HTTPS 请求、响应、也可以用作代理服务器。
-
-### 注册插件
-
-使用该选项前，你需要提前安装和注册 `@modern-js/plugin-proxy` 插件：
-
-import { PackageManagerTabs } from '@theme';
-
-<PackageManagerTabs command="add @modern-js/plugin-proxy -D" />
-
-安装完成后，在 `modern.config.ts` 文件中注册插件：
-
-```ts title="modern.config.ts"
-import { appTools, defineConfig } from '@modern-js/app-tools';
-import { proxyPlugin } from '@modern-js/plugin-proxy';
-
-export default defineConfig({
-  plugins: [appTools(), proxyPlugin()],
-});
-```
-
-### Object 类型
-
-`dev.proxy` 的值为 `Object` 时，对象的 `key` 对应匹配的 `pattern`，对象的 `value` 对应匹配的 `target`。
-
-例如：
-
-```ts title="modern.config.ts"
-export default defineConfig({
-  dev: {
-    proxy: {
-      'https://www.baidu.com': 'https://google.com.hk',
-      //可以通过 file 协议直接返回静态文件。
-      'https://example.com/api': 'file://./data.json',
-    },
-  },
-});
-```
-
-请参考 [whistle - 匹配模式](https://wproxy.org/whistle/pattern.html) 来了解详细用法。
-
-### String 类型
-
-`dev.proxy` 的值为 `string` 时， 可以用来指定单独的代理文件，例如：
-
-```ts title="modern.config.ts"
-export default defineConfig({
-  dev: {
-    proxy: './proxy.js',
-  },
-});
-```
-
-```js title="proxy.js"
-module.exports = {
-  name: 'my-app',
-  rules: `
-    ^example.com:8080/api/***   http://localhost:3001/api/$
-  `,
-};
-```
-
-### 启动代理
-
-执行 `dev`, 提示如下时，即代理服务器启动成功：
-
-```bash
-  Local:    http://localhost:8080/
-  Network:  http://192.168.0.1:8080/
-
-info      Starting proxy server.....
-success   Proxy server start on localhost:8899
-```
-
-访问 `localhost:8899`, 可以在 UI 界面上查看 Network 以及配置代理规则：
-
-![proxy ui 界面](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/dev-proxy.png)
-
-:::info
-https 代理自动安装证书需要获取 root 权限, 请根据提示输入密码即可。**密码仅在信任证书时使用，不会泄漏或者用于其他环节**。
-
-:::

package/docs/zh/components/global-proxy.mdx

@@ -1,29 +0,0 @@
-:::warning
-`@modern-js/plugin-proxy` 已不再维护，后续将不再发布新版本。请迁移到其他代理工具，比如 [whistle](https://github.com/avwo/whistle)。
-:::
-
-Modern.js 提供了开箱即用的全局代理插件 `@modern-js/plugin-proxy`，该插件底层基于 [whistle](https://github.com/avwo/whistle)，可用来查看、修改 HTTP/HTTPS 的请求和响应，也可作为 HTTP 代理服务器使用。
-
-### 设置代理规则
-
-引入代理插件并填写规则后，执行 `pnpm run dev`，Modern.js 会在开发服务器启动之后，自动启用代理服务器。
-
-具体代理规则，可通过 [`dev.proxy`](/configure/app/dev/proxy) 选项或 `config/proxy.js` 文件进行设置。
-
-### 代理服务器 UI 界面
-
-安装代理插件并配置代理规则后， 执行 `pnpm run dev` 命令：
-
-```bash
-  Local:    http://localhost:8080/
-  Network:  http://192.168.0.1:8080/
-
-info      Starting proxy server.....
-success   Proxy server start on localhost:8899
-```
-
-在控制台中可以看到代理服务器成功启动。
-
-访问 `http://localhost:8899`，显示下图所示的 UI 界面后，即可通过界面设置规则。
-
-![debug-proxy-ui](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/debug/debug-proxy-ui.png)

package/docs/zh/components/package-manager.mdx

@@ -1,11 +0,0 @@
-### packageManager
-
-问题：请选择包管理工具
-
-选项：
-
-- pnpm -- pnpm
-
-- Yarn -- yarn
-
-- npm -- npm

package/docs/zh/components/reduck-notify.mdx

@@ -1,27 +0,0 @@
-:::warning
-从 `MAJOR_VERSION.67.0` 起，Modern.js 不再默认提供 Reduck 状态管理能力。如果需要使用 Reduck，您需要安装并注册 state 插件。
-
-**安装步骤**
-
-1. 安装 `@modern-js/plugin-state` 依赖：
-
-```bash
-pnpm add @modern-js/plugin-state
-```
-
-2. 注册 state 插件：
-
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-import { statePlugin } from '@modern-js/plugin-state';
-
-export default defineConfig({
-  ...,
-  plugins: [
-    ...,
-    statePlugin(),
-  ],
-});
-```
-
-:::

package/docs/zh/components/reduck-tip.mdx

@@ -1,8 +0,0 @@
-
-
-:::info 补充信息
-默认情况下，本节所有 API 的导出包名为：`@modern-js/runtime/model`。
-
-如果是在 Modern.js 以外单独集成 Reduck，导出包名为：`@modern-js-reduck/react`。
-
-:::

package/docs/zh/configure/app/auto-load-plugin.mdx

@@ -1,66 +0,0 @@
----
-sidebar_position: 22
----
-
-# autoLoadPlugins
-
-- **类型：** `boolean`
-- **默认值：** `false`
-
-用于配置 Modern.js 是否开启自动注册插件。
-
-:::warning
-该配置不推荐使用，相比手动注册插件，该配置相对黑盒且无法为插件添加自定义配置。
-:::
-
-### 手动注册插件
-
-默认情况下，安装插件后，你需要在 `modern.config.ts` 文件中手动注册插件。
-
-```ts title="modern.config.ts"
-import { appTools, defineConfig } from '@modern-js/app-tools';
-import { bffPlugin } from '@modern-js/plugin-bff';
-
-export default defineConfig({
-  plugins: [appTools(), bffPlugin()],
-});
-```
-
-### 自动注册插件
-
-除了手段注册，Modern.js 还提供自动注册插件的方式: 将 `autoLoadPlugin` 配置项置为 `true`。
-
-```ts title="modern.config.ts"
-import { defineConfig } from '@modern-js/app-tools';
-
-export default defineConfig({
-  autoLoadPlugins: true,
-});
-```
-
-Modern.js 将通过以下几个步骤帮你自动注册插件
-
-1. Modern.js 在内部维护一份官方插件列表。
-
-```js
-const InternalPlugins = ['@modern-js/app-tools', '@modern-js/plugin-tailwindcss', ...];
-```
-
-2. Modern.js 将读取你的 `package.json` 文件，收集依赖信息。
-
-```json title="package.json"
-"dependencies": {
-  "@modern-js/plugin-tailwindcss": "x.x.x"
-  ...
-},
-"devDependencies": {
-  "@modern-js/app-tools": "x.x.x"
-  ...
-}
-```
-
-3. Modern.js 观察到你安装了 `@modern-js/plugin-tailwindcss` 和 `@modern-js/app-tools` 等依赖后，将会引入插件自动注册。
-
-可以注意到这种方式相对黑盒，你甚至对加载插件的过程是无感知的。我们希望更多的细节暴露给开发者，能让开发者去控制这一过程。
-
-**因此我们更加推荐你手动注册插件。**