@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

package/docs/zh/components/hono.mdx

@@ -0,0 +1,120 @@
+### 获取请求上下文
+
+在 BFF 函数中，有时需要获取请求上下文，来处理更多逻辑。此时，你可以通过 `useHonoContext` 来获取：
+
+```ts title="api/lambda/hello.ts"
+import { useHonoContext } from '@modern-js/server-runtime';
+
+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-backend-context)。
+:::
+
+### 获取 Cookie
+
+在 BFF 函数中获取 Cookie 时，需要通过 `useHonoContext` 获取请求上下文，然后使用 `c.req.header('cookie')` 获取 Cookie 字符串并手动解析：
+
+```ts title="api/lambda/cookies.ts"
+import { Api, Get } from '@modern-js/plugin-bff/hono-server';
+import { useHonoContext } from '@modern-js/server-runtime';
+
+// 解析 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/hono-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/hono-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/init-app.mdx

@@ -0,0 +1,111 @@
+Modern.js 提供了 `@modern-js/create` 工具来创建项目，不需要全局安装，直接使用 `npx` 按需运行即可。
+
+你可以在已有的空目录来创建项目：
+
+```bash
+mkdir myapp && cd myapp
+npx @modern-js/create@latest
+```
+
+也可以直接用新目录创建项目：
+
+```bash
+npx @modern-js/create@latest myapp
+```
+
+初始化 TanStack Router 模板：
+
+```bash
+npx @modern-js/create@latest myapp --router tanstack
+```
+
+初始化 Tailwind CSS v4 模板：
+
+```bash
+npx @modern-js/create@latest myapp --tailwind
+```
+
+同时初始化 TanStack Router + Tailwind CSS v4：
+
+```bash
+npx @modern-js/create@latest myapp --router tanstack --tailwind
+```
+
+初始化当前默认运行时的 BFF 模板：
+
+```bash
+npx @modern-js/create@latest myapp --bff
+```
+
+初始化带 Effect HttpApi 运行时的 BFF 模板：
+
+```bash
+npx @modern-js/create@latest myapp --bff-runtime effect
+```
+
+初始化带 Hono 运行时的 BFF 模板：
+
+```bash
+npx @modern-js/create@latest myapp --bff-runtime hono
+```
+
+使用 workspace 协议依赖初始化（用于在本地 monorepo 中联调未发布的 Modern.js 包）：
+
+```bash
+npx @modern-js/create@latest myapp --router tanstack --bff-runtime effect --workspace
+```
+
+`@modern-js/create` 会直接创建应用，不再提供问答界面：
+
+```bash
+🚀 欢迎使用 Modern.js
+
+📦 正在创建项目 "myapp"...
+
+✨ 项目创建成功！🎉
+
+📋 接下来你可以执行以下命令：
+
+📁 进入项目目录：
+
+  cd myapp
+
+🔧 初始化 Git 仓库：
+
+  git init
+
+📥 安装项目依赖：
+
+  pnpm install
+
+⚡ 启动开发服务器：
+
+  pnpm start
+```
+
+现在，项目结构如下：
+
+```
+.
+├── biome.json
+├── modern.config.ts
+├── package.json
+├── README.md
+├── src
+│   ├── modern-app-env.d.ts
+│   ├── modern.runtime.ts
+│   └── routes
+│       ├── index.css
+│       ├── layout.tsx
+│       └── page.tsx
+└── tsconfig.json
+```
+
+当启用 `--tailwind` 时，项目根目录会额外生成 `postcss.config.mjs` 和 `tailwind.config.ts`。
+
+当启用 `--bff` 或 `--bff-runtime effect` 时，会在 `modern.config.ts` 中启用 `@modern-js/plugin-bff`，生成 `api/effect/index.ts` 与 `shared/effect/api.ts`，并将 `bff.runtimeFramework` 设置为 `effect`。
+当启用 `--bff-runtime hono` 时，会在 `modern.config.ts` 中启用 `@modern-js/plugin-bff`，生成 `api/lambda/hello.ts`，并将 `bff.runtimeFramework` 设置为 `hono`。
+当启用 `--workspace` 时，`@modern-js/*` 依赖会使用 `workspace:*` 版本，便于本地 monorepo 联调。
+
+如果你需要公开的 UltraModern 预设路径，请从生成的
+`presetUltramodern(...)` 脚手架开始，再显式选择运行时分支。

package/docs/zh/components/init-rspack-app.mdx

@@ -0,0 +1,5 @@
+```bash
+$ npx @modern-js/create@latest myapp
+? 请选择开发语言：TS
+? 请选择包管理工具：pnpm
+```

package/docs/zh/components/internal-logger.mdx

@@ -0,0 +1,25 @@
+在 Modern.js 中，日志事件由 LoggerMonitor 处理，它会将日志输出到控制台。
+
+:::info
+内置的 LoggerMonitor 依赖了 [rslog](https://www.npmjs.com/package/rslog) 库。
+:::
+
+例如在项目中有意的抛出一个错误：
+
+```tsx title=routes/page.tsx
+import './index.css';
+
+const Index = () => <div className="container-box">{a}</div>;
+
+export default Index;
+```
+
+如果运行正常，可以在控制台看到如下输出：
+
+```shell
+> Local:    http://localhost:8080/
+> press h + enter to show shortcuts
+
+error   SSR Error - App Prerender, error = ReferenceError: a is not defined
+    at Index (/somepath/page.tsx:3:1)
+```

package/docs/zh/components/internal-metrics.mdx

@@ -0,0 +1,20 @@
+在 Modern.js 中，指标事件也由 LoggerMonitor 处理，它会将指标按照一定格式输出到控制台。
+
+:::info
+内置的 LoggerMonitor 依赖了 [rslog](https://www.npmjs.com/package/rslog) 库。
+:::
+
+在 Modern.js 中初始化的 `rslog` 实例默认在开发环境下会输出 `debug` 级别及以上的日志，在生产环境下会输出所有日志。而在内置的 `LoggerMonitor` 中，所有的指标事件都被输出为 Debug 日志。因此如果希望在开发环境查看指标事件的信息，需要添加额外的环境变量。
+
+开发者可以在运行 `dev` 命令时添加环境变量 `DEBUG=true`，如果运行正常，访问后可以在控制台看到如下输出：
+
+```shell
+> Local:    http://localhost:8080/
+> press h + enter to show shortcuts
+
+debug   SSR Debug - server-loader, cost: 2.000094, req.url = /
+debug   SSR Debug - ssr-prerender, cost: 6.99997, req.url = /
+debug   SSR Debug - ssr-render-html, cost: 0.999927, req.url = /
+debug   Debug - server-handle-request, cost: 19.999981, req.url = /
+debug     --> GET / 200 90ms
+```

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 @@
+支持所有 [i18next 初始化选项](https://www.i18next.com/overview/configuration-options)，常用选项说明如下：

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

@@ -0,0 +1,11 @@
+`i18next` 和 `react-i18next` 是 **Peer Dependency**，需要手动安装。
+
+:::note 版本一致性
+`@modern-js/plugin-i18n` 需要与项目中 `@modern-js/app-tools` 版本保持一致。
+:::
+
+
+```bash
+pnpm list @modern-js/app-tools
+pnpm add @modern-js/plugin-i18n@<version> i18next react-i18next
+```

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

@@ -0,0 +1,16 @@
+创建 `src/modern.runtime.ts`：
+
+```ts
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import i18next from 'i18next';
+
+// i18next 默认导出一个全局单例，多个应用共用会互相影响。
+// createInstance() 创建独立实例，确保每个应用有独立的语言状态。
+const i18nInstance = i18next.createInstance();
+
+export default defineRuntimeConfig({
+  i18n: {
+    i18nInstance,
+  },
+});
+```

package/docs/zh/components/international/introduce.mdx

@@ -0,0 +1,5 @@
+`@modern-js/plugin-i18n` 是 Modern.js 的国际化插件，基于 [i18next](https://www.i18next.com/) 和 [react-i18next](https://react.i18next.com/) 构建。
+
+- **插件本身**：负责与 Modern.js 框架的集成，如 SSR 语言传递、路由前缀处理等
+- **i18next**：核心翻译能力，如 `t()` 函数、插值、复数、命名空间。
+- **react-i18next**：React 组件和 Hook，如 `useTranslation`，实现与 React 生命周期的结合。

package/docs/zh/components/language-config.mdx

@@ -0,0 +1,9 @@
+### language
+
+问题：请选择开发语言
+
+选项：
+
+- TS -- ts
+
+- ES6+ -- js

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

@@ -0,0 +1,6 @@
+微前端（Micro-frontend，简称 MFE）是一种类似于微服务的架构，是一种由独立交付的多个前端应用组成整体的架构风格，它将前端应用分解成一些更小、更简单的能够独立开发、测试、部署的应用，而在用户看来仍然是内聚的单个产品。
+
+它主要解决了两个问题：
+
+- 随着项目迭代应用越来越庞大，难以维护。
+- 跨团队或跨部门协作开发项目导致效率低下的问题。

package/docs/zh/components/micro-master-manifest-config.mdx

@@ -0,0 +1,15 @@
+## manifest
+
+```ts
+interface Manifest {
+  getAppList?: () => Array<AppInfo>;
+}
+```
+
+### getAppList?
+
+通过 `getAppList` 配置，可以自定义如何获取远程列表数据
+
+```ts
+type GetAppList = () => Promise<Array<AppInfo>>;
+```

package/docs/zh/components/micro-runtime-config.mdx

@@ -0,0 +1,17 @@
+```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/module-federation.mdx

@@ -0,0 +1,7 @@
+模块联邦（Module Federation，简称 MF）是一种让多个 JavaScript 应用可以共享代码和资源的技术方案。它类似于服务端的微服务架构，允许你将大型应用拆分成多个独立的小应用，这些小应用可以独立开发、测试和部署，同时还能在运行时动态加载其他应用的模块。
+
+使用模块联邦可以解决多个前端应用之间代码重复的问题。传统方式下，如果多个应用需要使用相同的组件或工具函数，需要在每个应用中重复安装这些代码，导致代码重复、维护成本高、应用体积变大。使用模块联邦后，你可以将公共代码放在一个应用中，其他应用按需动态加载，实现代码共享，减少重复。
+
+Module Federation 2.0 支持 [Rspack](https://rspack.rs/) 构建工具，并提供了动态类型提示、Manifest、Federation Runtime、运行时插件系统和 Chrome Devtools 等增强功能，提供更好的开发体验和调试能力。你可以访问 [Module Federation 官方文档](https://module-federation.io/zh/index.html) 了解更多信息。
+
+Modern.js 提供了一个 Module Federation 的示例项目，请参考 [module-federation-examples - modernjs](https://github.com/module-federation/module-federation-examples/tree/db5bdbeee56f779999a2c591fc553eb94eb20b36/modernjs)。

package/docs/zh/components/nodeVersion.mdx

@@ -0,0 +1,28 @@
+在开始使用前，你需要安装 [Node.js](https://nodejs.org/)，并保证 Node.js 版本不低于 v20.19.5，**我们推荐使用 Node.js 22 的 LTS 版本**。
+
+你可以通过以下命令检查当前使用的 Node.js 版本：
+
+```bash
+node -v
+```
+
+如果你当前的环境中尚未安装 Node.js，或是安装的版本低于 v20.19.5，可以通过 [nvm](https://github.com/nvm-sh/nvm) 或 [fnm](https://github.com/Schniz/fnm) 安装需要的版本。
+
+下面是通过 nvm 安装 Node.js 22 LTS 版本的例子：
+
+```bash
+# 安装 Node.js 22 的长期支持版本
+nvm install 22 --lts
+
+# 将刚安装的 Node.js 22 设置为默认版本
+nvm alias default 22
+
+# 切换到刚安装的 Node.js 22
+nvm use 22
+```
+
+:::tip nvm 和 fnm
+nvm 和 fnm 都是 Node.js 版本管理工具。相对来说，nvm 较为成熟和稳定，而 fnm 是使用 Rust 实现的，比 nvm 提供了更好的性能。
+:::
+
+此外，在安装 nvm 或 fnm 后，然后只要仓库根目录下有内容为 `lts/jod` 的 `.nvmrc` 文件，进入这个仓库时就会自动安装或切换到正确的 Node.js 版本。

package/docs/zh/components/output-polyfill-extend.mdx

@@ -0,0 +1 @@
+Modern.js 还支持了基于浏览器 [UA](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/User-Agent) 信息的运行时按需 Polyfill 方案，具体使用姿势可查看 [运行时按需 Polyfill](/guides/advanced-features/compatibility.html#运行时按需-polyfill)

package/docs/zh/components/prerequisites.mdx

@@ -0,0 +1,18 @@
+### Node.js
+
+import NodeVersion from '@site-docs/components/nodeVersion.mdx';
+
+<NodeVersion />
+
+### pnpm
+
+推荐使用 [pnpm](https://pnpm.io/installation) 来管理依赖：
+
+```bash
+npm install -g pnpm@10
+```
+
+:::note
+Modern.js 同样支持使用 `yarn`、`npm` 进行依赖管理。
+
+:::

package/docs/zh/components/release-note.mdx

@@ -0,0 +1 @@
+根据官网 [Release Note](https://github.com/web-infra-dev/modern.js/releases)，开发者也可以手动将项目升级到想要的版本。

package/docs/zh/components/rsbuild-config-tooltip.mdx

@@ -0,0 +1,5 @@
+import RsbuildLink from '@site/src/components/RsbuildLink';
+
+:::info
+该配置项的使用方式与 Rsbuild 完全一致。详细信息请参考 <RsbuildLink configName={props.configName}/>。
+:::

package/docs/zh/components/rsbuild.mdx

@@ -0,0 +1,3 @@
+[Rsbuild](https://v2.rsbuild.rs/) 是一个基于 Rspack 的 web 构建工具，它的目标是为 Rspack 用户提供开箱即用的构建能力，使开发者能够在零配置的情况下启动一个 web 项目。
+
+Rsbuild 集成了社区中基于 Rust 的高性能工具，包括 Rspack 和 SWC，以提供一流的构建速度和开发体验。

package/docs/zh/components/rsc-deploy-tip.mdx

@@ -0,0 +1 @@
+

package/docs/zh/components/rspack.mdx

@@ -0,0 +1,3 @@
+[Rspack](https://rspack.rs/) 是一个基于 Rust 编写的高性能 JavaScript 打包工具， 它提供对 webpack 生态良好的兼容性，能够无缝替换 webpack， 并提供闪电般的构建速度。
+
+相较于 webpack，Rspack 的构建性能有明显提升，除了 Rust 带来的语言优势，这也来自于它的并行架构和增量编译等特性。经过 benchmark 验证，Rspack 可以带来 5 ～ 10 倍编译性能的提升。

package/docs/zh/components/rspackTip.mdx

@@ -0,0 +1,7 @@
+:::tip Rspack - 高性能 Web 构建工具
+
+import Rspack from './rspack.mdx';
+
+<Rspack />
+
+:::

package/docs/zh/components/self-route-example.mdx

@@ -0,0 +1,21 @@
+```tsx title="src/App.tsx"
+import { BrowserRouter, Route, Routes } from '@modern-js/runtime/router';
+import { StaticRouter } from '@modern-js/runtime/router/server';
+import { use } from 'react';
+import { RuntimeContext } from '@modern-js/runtime';
+
+const Router = typeof window === 'undefined' ? StaticRouter : BrowserRouter;
+
+export default () => {
+  const context = use(RuntimeContext);
+  const pathname = context?.request?.pathname;
+  return (
+    <Router location={pathname}>
+      <Routes>
+        <Route index element={<div>index</div>} />
+        <Route path="about" element={<div>about</div>} />
+      </Routes>
+    </Router>
+  );
+};
+```

package/docs/zh/components/serve-command.mdx

@@ -0,0 +1,22 @@
+## modern serve
+
+`modern serve` 命令用于在生产环境下启动 Modern.js 工程, 也可以用于在本地预览生产环境构建的产物。注意你需要提前执行 [`build`](/apis/app/commands#modern-build) 命令构建出对应产物。
+
+```bash
+Usage: modern serve [options]
+
+Options:
+  -c --config <config>  指定配置文件路径，可以为相对路径或绝对路径
+  -h, --help            显示命令帮助
+  --api-only            仅启动 API 接口服务
+```
+
+默认情况下，应用将会在 `localhost:8080` 启动，可以通过 `server.port` 修改 Server 端口号：
+
+```js
+export default defineConfig({
+  server: {
+    port: 8081,
+  },
+});
+```

package/docs/zh/components/ssr-monitor.mdx

@@ -0,0 +1,3 @@
+:::tip
+SSR 相关的数据监控已整合到 Monitors 模块中，详见 [Monitors](/guides/advanced-features/server-monitor/monitors)。
+:::

package/docs/zh/components/swc.mdx

@@ -0,0 +1,3 @@
+[SWC](https://swc.rs/) (Speedy Web Compiler) 是基于 `Rust` 语言编写的高性能 JavaScript 和 TypeScript 转译和压缩工具。在 Polyfill 和语法降级方面可以和 Babel 提供一致的能力，并且性能比 Babel 高出一个数量级。
+
+Modern.js 提供了开箱即用的 SWC 插件，可以为你的 Web 应用提供语法降级、Polyfill 以及压缩，并且移植了一些额外常见的 Babel 插件。

package/docs/zh/components/tech-stack-node-framework.mdx

@@ -0,0 +1 @@
+Modern.js Server 以 [Hono.js](https://hono.dev/) 作为服务端运行时框架。BFF 默认使用 `effect`，同时将 `hono` 保留为显式兼容运行时。Effect 与 Hono 的 BFF 运行时是严格模式，不存在隐式回退。你可以基于 Hono.js 生态扩展 Server，请参考 [自定义 Web Server](/guides/advanced-features/web-server.html)。

package/docs/zh/components/turtorials-example-list.mdx

@@ -0,0 +1,2 @@
+- [路由鉴权](/tutorials/examples/csr-auth.html)
+- ...

package/docs/zh/components/ua-polyfill.mdx

@@ -0,0 +1,44 @@
+### 运行时按需 Polyfill
+
+Modern.js 中还提供了基于浏览器 [UA](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/User-Agent) 信息的运行时按需 Polyfill 方案，相比于 Babel 优势如下：
+
+- 不会插入到代码中，只根据访问页面的设备，按需下发 Polyfill 代码 ，减少整体代码体积。
+- 相同浏览器会公用一份 Polyfill 代码。因此，随着项目越来越多，基于 UA 的 Polyfill 代码下发速度会越来越快，综合速度超过常规方案。
+
+Modern.js 提供了 `@modern-js/plugin-polyfill` 插件来实现该功能，可以通过安装该插件来开启该功能：
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs
+  command={{
+    npm: 'npm install @modern-js/plugin-polyfill',
+    yarn: 'yarn add @modern-js/plugin-polyfill',
+    pnpm: 'pnpm add @modern-js/plugin-polyfill',
+  }}
+/>
+
+然后在 `modern.config.ts` 中注册 Polyfill 插件:
+
+```ts title="modern.config.ts"
+import { polyfillPlugin } from '@modern-js/plugin-polyfill';
+
+export default defineConfig({
+  plugins: [..., polyfillPlugin()],
+});
+```
+
+配置 `output.polyfill` 为 `ua` 并且执行 `pnpm run build && pnpm run serve` 启动服务器后，访问页面可以看到 HTML 产物中包含如下脚本:
+
+```js
+<script src="/__polyfill__" crossorigin></script>
+```
+
+在 Chrome 51 下访问页面可以看到 `http://localhost:8080/__polyfill__` 返回内容如下:
+
+![ua-polyfill](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/ua-polyfill.png)
+
+:::caution 注意
+该功能只有在使用 Modern.js 内置的 Web Server 时才会生效。
+
+如果有自定义模版的需求，请参考 [HTML 模板](/guides/basic-features/html.html)。通过 `html.template` 或 `tools.html` 手动修改模版时，可能会导致该功能无法正确生效。
+:::