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

package/docs/en/plugin/server-plugins/api.mdx

@@ -1,3 +1,212 @@
 # Plugin API
 
-Comming soon...
+Modern.js's Server plugins allow you to extend and customize functionality during the server-side request processing phase, such as adding middleware, modifying request responses, etc.
+
+:::info
+
+Server plugins need to be configured via the `plugins` field in `server/modern.server.ts`.
+
+:::
+
+## Plugin Basic Structure
+
+A typical Server plugin structure is as follows:
+
+```typescript
+import type { ServerPlugin } from '@modern-js/server-runtime';
+
+const myServerPlugin = (): ServerPlugin => ({
+  name: '@my-org/my-server-plugin', // Plugin name, ensure uniqueness
+  setup: api => {
+    // Use the API here to register hooks, add middleware, etc.
+    api.onPrepare(() => {
+      const { middlewares } = api.getServerContext();
+      middlewares?.push({
+        name: 'my-middleware',
+        handler: async (c, next) => {
+          console.log('Processing request...');
+          await next();
+        },
+      });
+    });
+  },
+});
+
+export default myServerPlugin;
+```
+
+- `name`: A unique identifier for the plugin.
+- The `setup` function receives an `api` object, which provides all available Server plugin APIs.
+
+## Information Retrieval
+
+#### `api.getServerContext`
+
+Gets the context information of the Modern.js server.
+
+- **Returns:** A `ServerContext` object containing the following fields:
+
+| Field Name          | Type              | Description                           |
+| ------------------- | ----------------- | ------------------------------------- |
+| `middlewares`       | `MiddlewareObj[]` | Middleware list                       |
+| `renderMiddlewares` | `MiddlewareObj[]` | Render middleware list                |
+| `routes`            | `ServerRoute[]`   | Server routing information            |
+| `appDirectory`      | `string`          | Absolute path to the project root    |
+| `apiDirectory`      | `string`          | Absolute path to the API module dir  |
+| `lambdaDirectory`   | `string`          | Absolute path to the Lambda module dir|
+| `sharedDirectory`   | `string`          | Absolute path to the shared module dir|
+| `distDirectory`     | `string`          | Absolute path to the output directory|
+| `plugins`            | `ServerPlugin[]`  | List of currently registered plugins  |
+
+- **Example:**
+
+```typescript
+api.onPrepare(() => {
+  const serverContext = api.getServerContext();
+  console.log(`App directory: ${serverContext.appDirectory}`);
+  console.log(`${serverContext.plugins.length} plugins registered`);
+});
+```
+
+:::info
+The context information returned by `getServerContext` is read-only. Use `updateServerContext` if you need to modify it.
+:::
+
+---
+
+#### `api.getServerConfig`
+
+Gets the server configuration defined by the user in the `server/modern.server.ts` file.
+
+- **Returns:** The user-defined server configuration object.
+- **Example:**
+
+```typescript
+api.onPrepare(() => {
+  const serverConfig = api.getServerConfig();
+  if (serverConfig.middlewares) {
+    console.log('User has customized middleware configuration');
+  }
+});
+```
+
+---
+
+#### `api.getHooks`
+
+Gets all registered hook functions.
+
+- **Returns:** An object containing all hook functions.
+- **Example:**
+
+```typescript
+const hooks = api.getHooks();
+// Manually trigger the onPrepare hook
+await hooks.onPrepare.call();
+```
+
+:::warning
+In custom plugins, you can only manually call the hooks registered by the corresponding plugin and cannot call official hooks to avoid affecting the normal execution order of the application.
+:::
+
+---
+
+
+## Context Modification
+
+#### `api.updateServerContext`
+
+Updates the server context information.
+
+- **Type:** `api.updateServerContext(updateContext: DeepPartial<ServerContext>)`
+- **Parameters:**
+  - `updateContext`: The context object to update (partial update).
+- **Execution Phase:** Can be used at any stage.
+- **Example:**
+
+```typescript
+api.onPrepare(() => {
+  const context = api.getServerContext();
+  api.updateServerContext({
+    middlewares: [
+      ...context.middlewares,
+      {
+        name: 'new-middleware',
+        handler: async (c, next) => {
+          await next();
+        },
+      },
+    ],
+  });
+});
+```
+
+---
+
+
+## Lifecycle Hooks
+
+#### `api.onPrepare`
+
+Adds additional logic during the server preparation phase.
+
+- **Type:** `api.onPrepare(prepareFn: () => void | Promise<void>)`
+- **Parameters:**
+  - `prepareFn`: A preparation function, without parameters, can be asynchronous.
+- **Execution Phase:** After the server completes configuration validation and before applying middleware.
+- **Example:**
+
+```typescript
+api.onPrepare(async () => {
+  const { middlewares } = api.getServerContext();
+
+  // Add custom middleware
+  middlewares.push({
+    name: 'request-logger',
+    handler: async (c, next) => {
+      const start = Date.now();
+      await next();
+      const duration = Date.now() - start;
+      console.log(`Request duration: ${duration}ms`);
+    },
+  });
+});
+```
+
+:::info
+In the `onPrepare` hook, you can modify the context object returned by `getServerContext()` (such as `middlewares`, `renderMiddlewares`), and these modifications will take effect when the server starts.
+:::
+
+---
+
+#### `api.onReset`
+
+Adds additional logic when the server resets.
+
+- **Type:** `api.onReset(resetFn: (params: { event: ResetEvent }) => void | Promise<void>)`
+- **Parameters:**
+  - `resetFn`: A reset handler function that receives reset event parameters.
+    - `event.type`: Event type, possible values:
+      - `'repack'`: Repack event
+      - `'file-change'`: File change event
+    - `event.payload`: When `type` is `'file-change'`, contains an array of file change information.
+- **Execution Phase:** When files change or repack is needed.
+- **Example:**
+
+```typescript
+api.onReset(async ({ event }) => {
+  if (event.type === 'file-change') {
+    console.log('File changes detected:', event.payload);
+    // Perform cleanup or re-initialization operations
+  } else if (event.type === 'repack') {
+  }
+});
+```
+
+---
+
+
+## Other Notes
+
+- Refer to [Server Plugin Lifecycle](./life-cycle.mdx) to understand the execution order of plugin hooks.
+- The execution order of middleware can be controlled through the `order` field (`'pre'`, `'default'`, `'post'`), or through the `before` field to specify execution before other middleware.

package/docs/en/plugin/server-plugins/life-cycle.mdx

@@ -1,3 +1,43 @@
 # Life Cycle
 
-Comming soon...
+import Mermaid from '@site/src/components/Mermaid';
+
+<Mermaid>
+{`
+flowchart TD
+    init{{"Server Initialization"}}
+    load_config(Load User Config File)
+    server_plugin(Load Server Plugins<br><sub>Plugins registered in config file<br>Server plugins registered by CLI plugins<br>Plugins used by plugins</sub>)
+    registry_hooks(Register Hooks Functions<br><sub>Execute plugin setup function, register Hooks defined in plugins, logic in plugin setup will also execute here</sub>)
+
+    modifyConfig(modifyConfig<br><sub>Modify server configuration</sub>)
+    onPrepare(onPrepare<br><sub>Execute after server completes configuration validation, before applying middleware</sub>)
+    apply_middlewares(Apply Middleware<br><sub>Apply middleware according to order and before rules</sub>)
+
+    init --> load_config
+    load_config --> server_plugin
+    server_plugin --> registry_hooks
+    registry_hooks --> modifyConfig
+    modifyConfig --> onPrepare
+    onPrepare --> apply_middlewares
+
+    style init fill:#FDE68A,font-size:10px;
+    style load_config stroke-dasharray:5 5,fill:#86EFAC,font-size:10px;
+    style server_plugin stroke-dasharray:5 5,fill:#86EFAC,font-size:10px;
+    style registry_hooks stroke-dasharray:5 5,fill:#9CA3AF,font-size:10px;
+    style modifyConfig font-size:10px;
+    style onPrepare font-size:10px;
+    style apply_middlewares font-size:10px;
+`}
+</Mermaid>
+
+:::info
+
+**Runtime Hooks**
+
+The `onReset` hook is triggered at runtime when files change or code recompilation (rspack) is needed. It is not part of the initialization flow, so it is not shown in the diagram above.
+
+- **Trigger Timing**: File changes (`event.type: 'file-change'`) or code recompilation (rspack) completion (`event.type: 'repack'`)
+- **Use Cases**: Clearing cache, re-initializing resources, etc.
+
+:::

package/docs/zh/apis/app/commands.mdx

@@ -19,7 +19,6 @@ Options:
   -e --entry <entry>    指定入口，只编译特定的页面
   -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
   -h, --help            显示命令帮助
-  --analyze             分析构建产物体积，查看各个模块打包后的大小
   --web-only            仅启动 Web 服务
   --api-only            仅启动 API 接口服务
 ```
@@ -79,31 +78,8 @@ Options:
   -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
   -h, --help  显示命令帮助
   -w --watch  开启 watch 模式, 监听文件变更并重新构建
-  --analyze   分析构建产物体积，查看各个模块打包后的大小
 ```
 
-### 分析构建产物体积
-
-执行 `npx modern build --analyze` 命令，可以在打包生产环境代码的同时，产出一个分析构建产物体积的 HTML 文件：
-
-```
-Bundle Analyzer saved report to /example/dist/report.html
-
-info    Production file sizes:
-
-  File                                      Size         Gzipped
-  dist/static/js/lib-react.09721b5c.js      152.6 kB     49.0 kB
-  dist/html/main/index.html                 5.8 kB       2.5 kB
-  dist/static/js/main.3568a38e.js           3.5 kB       1.4 kB
-  dist/static/css/main.03221f72.css         1.4 kB       741 B
-```
-
-手动在浏览器中打开上述 HTML 文件，可以看到打包产物的瓦片图，并进行包体积分析和优化：
-
-<img src="https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/mwa-build-analyze-8784f762c1ab0cb20935829d5f912c4c.png" />
-
-> 该功能基于 [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) 实现。
-
 ## modern new
 
 `modern new` 命令用于在已有项目中添加项目元素。
@@ -174,7 +150,7 @@ Options:
 
 ## modern inspect
 
-`modern inspect` 命令用于查看项目的 Modern.js 配置、[Rsbuild 配置](https://rsbuild.rs/zh/config/index) 以及 webpack 或 Rspack 配置。
+`modern inspect` 命令用于查看项目的 Modern.js 配置、[Rsbuild 配置](https://rsbuild.rs/zh/config/index) 以及 Rspack 配置。
 
 ```bash
 Usage: modern inspect [options]
@@ -191,7 +167,7 @@ Options:
 
 - `modern.js.config.mjs`: 表示当前使用的 Modern.js 配置。
 - `rsbuild.config.mjs`: 表示在构建时使用的 Rsbuild 配置。
-- `webpack.config.web.mjs`: 表示在构建时使用的 webpack 配置。
+- `rspack.config.web.mjs`: 表示在构建时使用的 Rspack 配置。
 
 ```bash
 ➜ npx modern inspect
@@ -199,7 +175,7 @@ Options:
 Inspect config succeed, open following files to view the content:
 
   - Rsbuild Config: /root/my-project/dist/rsbuild.config.mjs
-  - Webpack Config (web): /root/my-project/dist/webpack.config.web.mjs
+  - Rspack Config (web): /root/my-project/dist/rspack.config.web.mjs
   - Modern.js Config: /root/my-project/dist/modern.js.config.mjs
 ```
 
@@ -221,7 +197,7 @@ modern inspect --verbose
 
 ### SSR 构建配置
 
-如果项目开启了 SSR 能力，则在 `dist` 目录会另外生成一份 `webpack.config.node.mjs` 文件，对应 SSR 构建时的 webpack 配置。
+如果项目开启了 SSR 能力，则在 `dist` 目录会另外生成一份 `rspack.config.node.mjs` 文件，对应 SSR 构建时的 Rspack 配置。
 
 ```bash
 ➜ npx modern inspect
@@ -229,8 +205,8 @@ modern inspect --verbose
 Inspect config succeed, open following files to view the content:
 
   - Rsbuild Config: /root/my-project/dist/rsbuild.config.mjs
-  - Webpack Config (web): /root/my-project/dist/webpack.config.web.mjs
-  - Webpack Config (node): /root/my-project/dist/webpack.config.node.mjs
+  - Rspack Config (web): /root/my-project/dist/rspack.config.web.mjs
+  - Rspack Config (node): /root/my-project/dist/rspack.config.node.mjs
   - Modern.js Config: /root/my-project/dist/modern.js.config.mjs
 ```
 

package/docs/zh/components/bff-operator-code.mdx

@@ -0,0 +1,5 @@
+import FrameworkCode from '@site/src/components/FrameworkCode';
+
+<FrameworkCode sourcePath="@modern-js/plugin-bff/server">
+  {props.children}
+</FrameworkCode>

package/docs/zh/components/bff-upload.mdx

@@ -1,5 +1,3 @@
-BFF 搭配运行时框架提供了文件上传能力，支持一体化调用及纯函数手动调用。
-
 ### BFF 函数
 
 首先创建 `api/lambda/upload.ts` 文件：

package/docs/zh/components/bundler.mdx

@@ -1,3 +1,3 @@
-指 [webpack](https://webpack.js.org/)、[Rspack](https://rspack.rs/) 等模块打包工具。
+指 [Rspack](https://rspack.rs/) 等模块打包工具。
 
 打包工具的主要目标是将 JavaScript、CSS 等文件打包在一起，打包后的文件可以在浏览器、Node.js 等环境中使用。当 Bundler 处理 Web 应用时，它会构建一个依赖关系图，其中包含应用需要的各个模块，然后将所有模块打包成一个或多个 bundle。

package/docs/zh/components/enable-bff.mdx

@@ -23,7 +23,7 @@ pnpm add @modern-js/plugin-bff@<版本号>
 
 :::
 
-2. 配置 modern.config.ts
+2. 配置 `modern.config.ts`
 
 在 `modern.config.[tj]s` 文件中导入并添加 BFF 插件：
 
@@ -47,6 +47,10 @@ export default defineConfig({
       ..., // other paths,
       "@api/*": ["./api/lambda/*"]
     }
-  }
+  },
+  "include": [
+    ..., // 其他 include 目录
+    "api"  // 添加 api 目录
+  ]
 }
 ```

package/docs/zh/components/enable-ssg.mdx

@@ -9,6 +9,7 @@ pnpm add @modern-js/plugin-ssg
 ```
 
 :::tip 版本一致性
+
 请确保 `@modern-js/plugin-ssg` 的版本与项目中 `@modern-js/app-tools` 的版本保持一致。Modern.js 的所有官方包使用统一版本号发布，版本不一致可能导致兼容性问题。
 
 请先查看 `@modern-js/app-tools` 的版本，然后安装相同版本的 `@modern-js/plugin-ssg`：
@@ -44,4 +45,5 @@ export default defineConfig({
 - 单入口请使用 `output.ssg`。
 - 多入口请使用 `output.ssgByEntries`。
 - 当仅设置 `output.ssg: true` 且未配置 `output.ssgByEntries` 时，所有入口下的所有路由都会作为 SSG 路由处理。
-  :::
+
+:::

package/docs/zh/components/esbuild.mdx

@@ -1,3 +1,3 @@
-[esbuild](https://esbuild.github.io/) 是一款基于 Golang 开发的前端构建工具，具有打包、编译和压缩 JavaScript 代码的功能，相比传统的打包编译工具，esbuild 在性能上有显著提升。在代码压缩方面，相比 webpack 内置的 terser 压缩器，esbuild 在性能上有数十倍的提升。
+[esbuild](https://esbuild.github.io/) 是一款基于 Golang 开发的前端构建工具，具有打包、编译和压缩 JavaScript 代码的功能，相比传统的打包编译工具，esbuild 在性能上有显著提升。在代码压缩方面，esbuild 在性能上有数十倍的提升。
 
-Modern.js 提供了 esbuild 插件，让你能使用 esbuild 代替 babel-loader、ts-loader 和 terser 等库进行代码编译和压缩。在大型工程中启用 esbuild 后，**可以大幅度减少代码编译和压缩所需的时间，同时有效避免 OOM (heap out of memory) 问题**。
+Modern.js 提供了 esbuild 插件，让你能使用 esbuild 代替 babel-loader、ts-loader 等库进行代码编译和压缩。在大型工程中启用 esbuild 后，**可以大幅度减少代码编译和压缩所需的时间，同时有效避免 OOM (heap out of memory) 问题**。

package/docs/zh/components/extend-bff-function.mdx

@@ -1,5 +1,3 @@
-普通的 BFF 函数写法有时并不能满足需求，我们正在设计一套更强大的 BFF 函数写法，让开发者更方便地扩展 BFF 函数。
+普通的 BFF 函数写法有时并不能满足需求，例如业务场景下复杂的 TS 类型需要，EdenX 提供了一种更强大的 BFF 函数写法。
 
-:::note
-敬请期待
-:::
+详细内容可参考 - [创建可扩展的 BFF 函数](/guides/advanced-features/bff/operators)。

package/docs/zh/components/hono.mdx

@@ -0,0 +1,119 @@
+### 获取请求上下文
+
+在 BFF 函数中，有时需要获取请求上下文，来处理更多逻辑。此时，你可以通过 `useHonoContext` 来获取：
+
+```ts title="api/lambda/hello.ts"
+import { useHonoContext } from '@modern-js/plugin-bff/server';
+
+export const get = async () => {
+  const c = useHonoContext();
+  console.info(`access url: ${c.req.url}`);
+  return 'Hello Modern.js';
+};
+```
+
+:::info
+详细内容可以参考 [useHonoContext](/apis/app/runtime/bff/use-hono-context)。
+:::
+
+### 获取 Cookie
+
+在 BFF 函数中获取 Cookie 时，需要通过 `useHonoContext` 获取请求上下文，然后使用 `c.req.header('cookie')` 获取 Cookie 字符串并手动解析：
+
+```ts title="api/lambda/cookies.ts"
+import { Api, Get, useHonoContext } from '@modern-js/plugin-bff/server';
+
+// 解析 Cookie 字符串的辅助函数
+function parseCookies(
+  cookieHeader: string | undefined,
+): Record<string, string> {
+  const cookies: Record<string, string> = {};
+  if (!cookieHeader) return cookies;
+
+  cookieHeader.split(';').forEach(cookie => {
+    const [name, ...rest] = cookie.trim().split('=');
+    if (name) {
+      cookies[name] = rest.join('=');
+    }
+  });
+
+  return cookies;
+}
+
+export const getCookies = Api(Get('/cookies'), async () => {
+  const c = useHonoContext();
+  const cookieHeader = c.req.header('cookie');
+  const cookies = parseCookies(cookieHeader);
+  const token = cookies.token;
+  const sessionId = cookies.sessionId;
+  return {
+    hasToken: !!token,
+    token: token || null,
+    sessionId: sessionId || null,
+  };
+});
+```
+
+:::caution 注意
+`c.req.cookie()` 方法在当前版本中不存在，需要使用 `c.req.header('cookie')` 获取 Cookie 字符串，然后手动解析。
+:::
+
+### 定义 BFF 函数
+
+使用 Hono 作为运行时框架时，可以通过 [Api 函数](/guides/advanced-features/bff/operators.html) 定义接口：
+
+```ts title="api/lambda/user.ts"
+import { Api, Get, Query } from '@modern-js/plugin-bff/server';
+import { z } from 'zod';
+
+const QuerySchema = z.object({
+  id: z.string(),
+});
+
+export const getUser = Api(
+  Get('/user'),
+  Query(QuerySchema),
+  async ({ query }) => {
+    return {
+      id: query.id,
+      name: 'Modern.js',
+      email: 'modernjs@bytedance.com',
+    };
+  },
+);
+```
+
+:::info
+更多关于 Api 函数和操作符的详细内容，可以参考 [创建可扩展的 BFF 函数](/guides/advanced-features/bff/operators.html)。
+:::
+
+### 使用中间件
+
+Hono 支持丰富的中间件生态，可以在 BFF 函数中使用中间件：
+
+```ts title="api/lambda/user.ts"
+import { Api, Get, Middleware } from '@modern-js/plugin-bff/server';
+
+export const getUser = Api(
+  Get('/user'),
+  Middleware(async (c, next) => {
+    // 在中间件中可以访问 Hono 的 Context
+    c.res.headers.set('X-Powered-By', 'Modern.js');
+    await next();
+  }),
+  async () => {
+    return {
+      name: 'Modern.js',
+      email: 'modernjs@bytedance.com',
+    };
+  },
+);
+```
+
+:::info
+更多关于中间件的详细内容，可以参考 [创建可扩展的 BFF 函数](/guides/advanced-features/bff/operators.html#中间件-middleware)。
+:::
+
+### 更多 Hono 文档
+
+更多关于 Hono 的详细信息可查看 [Hono 官方文档](https://hono.dev/)。

package/docs/zh/components/international/custom-instance-code.mdx

@@ -0,0 +1,16 @@
+```ts
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import i18next from 'i18next';
+
+// 创建自定义实例
+const customI18n = i18next.createInstance({
+  // 自定义配置
+});
+
+export default defineRuntimeConfig({
+  i18n: {
+    i18nInstance: customI18n,
+  },
+});
+```
+

package/docs/zh/components/international/init-options-desc.mdx

@@ -0,0 +1 @@
+`initOptions` 会传递给 i18next 的 `init` 方法，支持所有 i18next 配置选项：

package/docs/zh/components/international/install-command.mdx

@@ -2,6 +2,21 @@
 pnpm add @modern-js/plugin-i18n i18next react-i18next
 ```
 
+:::tip 版本一致性
+请确保 `@modern-js/plugin-i18n` 的版本与项目中 `@modern-js/app-tools` 的版本一致。所有 Modern.js 官方包都使用统一的版本号发布，版本不匹配可能会导致兼容性问题。
+
+请先检查 `@modern-js/app-tools` 的版本，然后安装相同版本的 `@modern-js/plugin-i18n`：
+
+```bash
+# 检查当前 @modern-js/app-tools 的版本
+pnpm list @modern-js/app-tools
+
+# 安装相同版本的 @modern-js/plugin-i18n
+pnpm add @modern-js/plugin-i18n@<version> i18next react-i18next
+```
+
+:::
+
 :::info
 `i18next` 和 `react-i18next` 是 peer dependencies，需要手动安装。
 

package/docs/zh/components/international/instance-code.mdx

@@ -0,0 +1,26 @@
+创建 `src/modern.runtime.ts` 文件并配置 i18n 运行时选项：
+
+```ts
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import i18next from 'i18next';
+
+// 建议创建一个新的 i18next 实例，避免使用全局默认实例
+const i18nInstance = i18next.createInstance();
+
+export default defineRuntimeConfig({
+  i18n: {
+    i18nInstance: i18nInstance,
+    initOptions: {
+      fallbackLng: 'en',
+      supportedLngs: ['zh', 'en'],
+    },
+  },
+});
+```
+
+:::info
+`modern.runtime.ts` 是运行时配置文件，用于配置 i18next 的初始化选项。即使是最基础的配置，也建议创建此文件以确保插件正常工作。
+
+建议使用 `i18next.createInstance()` 创建一个新的实例，而不是直接使用默认导出的 `i18next`，这样可以避免全局状态污染，并确保每个应用都有独立的 i18n 实例。
+
+:::

package/docs/zh/configure/app/builder-plugins.mdx

@@ -18,8 +18,7 @@ Rsbuild 是 Modern.js 底层的构建工具，请阅读 [构建能力](/guides/c
 该选项**用于配置 Rsbuild 构建插件**，如果你需要配置其他类型的插件，请选择对应的配置方式：
 
 - 配置 Modern.js 框架插件，请使用 [plugins](/configure/app/plugins) 配置项。
-- 配置 Rspack 或 webpack 插件，请使用 [tools.bundlerChain](/configure/app/tools/bundler-chain) 配置项。
-- 配置 Babel 插件，请使用 [tools.babel](/configure/app/tools/babel) 配置项。
+- 配置 Rspack 插件，请使用 [tools.bundlerChain](/configure/app/tools/bundler-chain) 配置项。
 
 ## 何时使用