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

package/docs/zh/apis/app/hooks/config/icon.mdx

@@ -0,0 +1,29 @@
+---
+title: icon.*
+sidebar_position: 2
+---
+
+# Apple Touch Icon
+
+当项目根目录的 `config` 目录下存在 `icon.*` 文件时，Modern.js 会自动将该文件设置到 [html.appIcon](/configure/app/html/app-icon) 配置项中，用于生成 iOS 系统下的 Apple Touch Icon 图标。
+
+```
+./config
+└── icon.png
+```
+
+构建完成后，可以看到 HTML 中自动生成了以下标签：
+
+```html
+<link rel="apple-touch-icon" sizes="180x180" href="/static/image/icon.png" />
+```
+
+## 查找顺序
+
+在设置 app icon 时，Modern.js 会按以下顺序寻找文件：
+
+- `icon.png`
+- `icon.jpg`
+- `icon.jpeg`
+- `icon.svg`
+- `icon.ico`

package/docs/zh/apis/app/hooks/config/mock.mdx

@@ -0,0 +1,7 @@
+---
+title: mock/
+sidebar_position: 5
+---
+# mock/
+
+当项目目录下存在 `config/mock/index.js` 时，Modern.js 在开发环节将自动开启 Mock 服务。

package/docs/zh/apis/app/hooks/config/public.mdx

@@ -0,0 +1,30 @@
+---
+title: public/
+sidebar_position: 3
+---
+# public/
+
+`public/` 目录中可以放置任意格式的静态资源文件，文件会被服务端部署到对应的应用域名下。
+
+## 说明
+
+文件路由基于目录结构的约定，其中，`public/` 为根目录，对应 Web 应用根路径。
+
+例如 `config/public/sdk/index.js` 文件，在部署后将会被部署在 `${domain}/sdk/index.js` 下。
+
+## 场景
+
+例如 `robots.txt`，`auth.xml` 等第三方系统需要的认证文件。
+
+或者是给其他业务方（要求路由不变）的 SDK，也可以是无需入口的 HTML 文件等。
+
+:::info
+对于需要在源码中通过 import 引用的静态资源（比如 SVG 图片），建议放到 `src/assets` 目录下进行管理。
+
+:::
+
+## 代码压缩
+
+如果目录下的文件是一个 `.js` 文件，在生产环境构建时，会自动对其进行代码压缩。
+
+如果该文件以 `.min.js` 结尾，则不会经过代码压缩处理。

package/docs/zh/apis/app/hooks/config/upload.mdx

@@ -0,0 +1,54 @@
+---
+title: upload/
+sidebar_position: 4
+---
+# upload/
+
+`upload/` 目录中可以放置任意格式的静态资源文件。
+
+## 说明
+
+在开发环境下，该目录下的静态资源文件会被托管在 `/upload` 路径下。构建应用产物后，该目录下的文件会被复制到产物目录中。
+
+该文件约定主要用于开发者使用插件，主动上传静态资源文件到 CDN。
+
+## 场景
+
+例如 `google-analysis.js` 等项目自用的 SDK（通常需要 HTTP 缓存）。
+
+图片、字体文件、通用 CSS 等。
+
+## 代码压缩
+
+如果目录下的文件是一个 `.js` 文件，在生产环境构建时，会自动对其进行代码压缩。
+
+如果该文件以 `.min.js` 结尾，则不会经过代码压缩处理。
+
+## 更多用法
+
+在 React 组件中，可以通过[内置环境变量](/guides/basic-features/env-vars.html#asset_prefix)来添加该前缀：
+
+```tsx
+export default () => {
+  return (
+    <img src={`${process.env.ASSET_PREFIX}/upload/banner.png`}></img>
+  );
+};
+```
+
+另外，不论是在 [自定义 HTML](/guides/basic-features/html) 中，或是在 [`config/public/`](/apis/app/hooks/config/public) 下的任意 HTML 文件中，都可以直接使用 HTML 标签引用 `config/upload/` 目录下的资源：
+
+```html
+<script src="/upload/index.js"></script>
+```
+
+如果设置了 [`dev.assetPrefix`](/configure/app/dev/asset-prefix) 或 [`output.assetPrefix`](/configure/app/output/asset-prefix) 前缀，也可以直接使用模板语法添加该前缀：
+
+```html
+<script src="<%=assetPrefix %>/upload/index.js"></script>
+```
+
+:::info
+Modern.js 没有支持在 `config/public/*.css`（例如 background-image）中通过 URL 使用 `config/upload/` 下的文件。
+
+:::

package/docs/zh/apis/app/hooks/modern-config.mdx

@@ -0,0 +1,9 @@
+---
+title: modern.config.ts
+sidebar_position: 8
+---
+# modern.config.ts
+
+Modern.js 配置文件, 通过该文件可以对当前项目的各个方面进行个性化配置。
+
+了解配置的具体用法，请参考[配置使用](/configure/app/usage)。

package/docs/zh/apis/app/hooks/server/server.mdx

@@ -0,0 +1,10 @@
+---
+title: modern.server.ts
+sidebar_position: 1
+---
+
+# modern.server.ts
+
+扩展 Modern.js Server 的文件，在此文件中可以给 Modern.js 工程启动的 Server 配置 [Middleware](/guides/advanced-features/web-server.html#middleware) 、 [RenderMiddleware](/guides/advanced-features/web-server.html#rendermiddleware) 或 [Plugin](/guides/advanced-features/web-server.html#plugin)。
+
+可以对请求和响应进行拦截处理，鉴权与角色、请求预处理、异常兜底等。也可在内置处理逻辑（包括路由匹配、资源寻址、头部注入、页面渲染，静态 Web 托管）插入特定的业务逻辑。

package/docs/zh/apis/app/hooks/shared.mdx

@@ -0,0 +1,7 @@
+---
+title: shared/
+sidebar_position: 5
+---
+# shared/
+
+共享源码目录。当项目在 `api/`、`server/`、`src/` 下有公共代码时，可将这些代码放到 `shared` 目录下，而不是直接引用。

package/docs/zh/apis/app/hooks/src/app.mdx

@@ -0,0 +1,36 @@
+---
+title: App.tsx
+sidebar_position: 1
+---
+
+# App.tsx
+
+应用使用 [自控路由](/guides/concept/entries.html#自控式路由) 时的入口标识符。
+
+`App.tsx` 并不是实际的应用入口，Modern.js 会自动生成真正的构建打包的入口文件, 内容大致如下：
+
+```js
+// runtime-global-context
+import { setGlobalContext } from '@modern-js/runtime/context';
+import App from '@_modern_js_src/App';
+
+setGlobalContext({
+  App,
+});
+
+// index.tsx
+import './runtime-global-context';
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+const ModernRoot = createRoot();
+
+render(<ModernRoot />, 'root');
+```
+
+`createRoot` 执行时，会去获取注册的 Global App，生成真实的 React 组件。
+
+:::note
+在多入口的场景下，每个入口都可以拥有独立的 `App.tsx`，详见[入口](/guides/concept/entries)。
+
+:::

package/docs/zh/apis/app/hooks/src/entry.mdx

@@ -0,0 +1,39 @@
+---
+title: entry.ts
+sidebar_position: 4
+---
+
+# entry.tsx
+
+通常情况下[`routes/`](/apis/app/hooks/src/routes.html) 和 [`App.tsx`](/apis/app/hooks/src/app) 钩子文件已经能满足我们的需求，当我们需要在组件渲染之前添加自定义行为或者完全接管 Rspack 打包入口时，可以在 `src` 或者入口目录下放置 `entry.ts`。下面分两种情况进行讨论。
+
+## 在组件渲染前添加自定义行为
+
+在 `src/entry.ts` 中这样实现：
+
+```js title=src/entry.tsx
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+const ModernRoot = createRoot();
+
+async function beforeRender() {
+  // todo
+}
+
+beforeRender().then(() => {
+  render(<ModernRoot />);
+});
+```
+
+## 完全接管 Rspack 入口
+
+当项目未安装 `@modern-js/runtime` 依赖时， `src/entry.tsx?` 即为真正的 Rspack 打包入口文件, 可以直接像使用 create-react-app 等脚手架一样组织代码：
+
+```js title=src/entry.jsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(<App />);
+```

package/docs/zh/apis/app/hooks/src/entry.server.mdx

@@ -0,0 +1,56 @@
+---
+title: entry.server.tsx
+sidebar_position: 5
+---
+
+# entry.server.tsx
+
+当项目开启 `server.ssr` 时，Modern.js 生成一个默认的 Server-Side 入口。示例代码如下：
+
+```tsx title="entry.server.tsx"
+import {
+  renderString,
+  createRequestHandler,
+  type HandleRequest,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
+  const body = await renderString(request, <ServerRoot />, options);
+
+  return new Response(body, {
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```
+
+## 添加自定义行为
+
+如果用户需自定义 Server-Side Rendering 入口，可以在 `src/entry.server.ts`、`src/{entryName}/entry.server.ts` 中自定义 server 入口。
+
+```tsx title="src/entry.server.tsx"
+import {
+  renderString,
+  createRequestHandler,
+  type HandleRequest,
+} from '@modern-js/runtime/ssr/server';
+
+const handleRequest: HandleRequest = async (request, ServerRoot, options) => {
+  // do something before rendering
+  const body = await renderString(request, <ServerRoot />, options);
+
+  const newBody = body + '<div>Byte-Dance</div>';
+
+  return new Response(newBody, {
+    headers: {
+      'content-type': 'text/html; charset=UTF-8',
+      'x-custom-header': 'abc',
+    },
+  });
+};
+
+export default createRequestHandler(handleRequest);
+```

package/docs/zh/apis/app/hooks/src/modern.runtime.mdx

@@ -0,0 +1,9 @@
+---
+title: modern.runtime.ts
+sidebar_position: 4
+---
+# modern.runtime.ts
+
+Modern.js Runtime 配置文件, 通过该文件可以对当前项目的 Runtime 能力进行个性化配置。
+
+了解配置的具体用法，请参考 [Runtime 配置](/configure/app/runtime/0-intro.html)。

package/docs/zh/apis/app/hooks/src/routes.mdx

@@ -0,0 +1,90 @@
+---
+title: routes/
+sidebar_position: 2
+---
+# routes/
+
+应用使用 [约定式路由](/guides/basic-features/routes/routes#约定式路由) 时的入口标识。
+
+约定式路由以 `routes/` 为约定的入口， 会分析 `src/routes` 目录下的文件得到客户端路由配置。
+
+任何在 `src/routes` 下的 `layout.tsx` 和 `page.tsx` 都会作为应用的路由：
+
+```bash
+.
+└── routes
+    ├── layout.tsx  # [!code highlight]
+    ├── page.tsx # [!code highlight]
+    └── user
+        ├── layout.tsx
+        └── page.tsx
+```
+
+## 基本示例
+
+`routes` 目录下的目录名会作为路由 url 的映射，其中 `layout.tsx` 中作为布局组件，`page.tsx` 作为内容组件，是整条路由的叶子节点，例如以下目录结构：
+
+```bash
+.
+└── routes
+    ├── page.tsx
+    └── user
+        └── page.tsx
+```
+
+会产出下面两条路由：
+
+- `/`
+- `/user`
+
+## 动态路由
+
+如果路由文件的目录名以 `[]` 命名，生成的路由会作为动态路由。例如以下文件目录：
+
+```
+└── routes
+    ├── [id]
+    │   └── page.tsx
+    ├── blog
+    │   └── page.tsx
+    └── page.tsx
+```
+
+`routes/[id]/page.tsx` 文件会转为 `/:id` 路由。除了可以确切匹配的 `/blog` 路由，其他所有 `/xxx` 都会匹配到该路由。
+
+在组件中，可以通过 [useParams](/apis/app/runtime/router/router#useparams) 获取对应命名的参数。
+
+在使用 [loader](/guides/basic-features/data/data-fetch#loader-函数) 函数获取数据时，`params` 会作为 `loader` 函数的入参，通过 `params` 的属性可以获取到对应的参数。
+
+## 布局组件
+
+如下面的例子，可以通过添加 `layout.tsx`，为所有路由组件添加公共的布局组件：
+
+```bash
+.
+└── routes
+    ├── layout.tsx
+    ├── page.tsx
+    └── user
+        ├── layout.tsx
+        └── page.tsx
+```
+
+在布局组件中可以通过使用 `<Outlet>` 表示子组件：
+
+```tsx title=routes/layout.tsx
+import { Link, Outlet, useLoaderData } from '@modern-js/runtime/router';
+
+export default () => {
+  return (
+    <>
+      <Outlet></Outlet>
+    </>
+  );
+};
+```
+
+:::note
+`<Outlet>` 是 React Router v7 中新的 API，详情可以查看 [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
+
+:::

package/docs/zh/apis/app/hooks/src/server.mdx

@@ -0,0 +1,7 @@
+---
+title: '*.[server|node].tsx'
+sidebar_position: 8
+---
+# *.[server|node].tsx
+
+应用项目中使用，用于放置服务端代码，当 `*.tsx` 和 `*.[server|node].tsx` 共存时，SSR 在服务端执行渲染时，会优先使用 `*.[server|node].tsx` 文件，而不是 `*.tsx` 文件。

package/docs/zh/apis/app/runtime/_meta.json

@@ -0,0 +1,32 @@
+[
+  {
+    "type": "dir",
+    "name": "core",
+    "label": "Core",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "router",
+    "label": "Router",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "ssr",
+    "label": "SSR",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "bff",
+    "label": "BFF",
+    "collapsed": true
+  },
+  {
+    "type": "dir",
+    "name": "utility",
+    "label": "Utility",
+    "collapsed": true
+  }
+]

package/docs/zh/apis/app/runtime/bff/use-backend-context.mdx

@@ -0,0 +1,31 @@
+---
+title: useHonoContext
+---
+# useHonoContext
+
+用于在一体化 BFF 函数中获取后端请求上下文。
+
+
+## 使用姿势
+
+```ts
+import { useHonoContext } from '@modern-js/server-runtime';
+```
+
+## 函数签名
+
+`function useHonoContext(): Context`
+
+## 示例
+
+开发者可以通过 `context` 获取更多的请求信息，例如设置响应头：
+
+```ts
+import { useHonoContext } from '@modern-js/server-runtime';
+
+export async function get() {
+  const c = useHonoContext();
+  c.res.headers.set('x-bff-api', 'true');
+  // ...
+}
+```

package/docs/zh/apis/app/runtime/core/create-root.mdx

@@ -0,0 +1,22 @@
+---
+title: createRoot
+---
+# createRoot
+
+用于创建 Modern.js 提供的根组件，该根组件会自动注册 Runtime 插件，并完成 Runtime 插件初始化。
+
+## 使用姿势
+
+```ts
+import { createRoot } from '@modern-js/runtime/react';
+```
+
+## 函数签名
+
+```ts
+export function createRoot(UserApp?: React.ComponentType | null): React.ComponentType<any>;
+```
+
+### 参数
+
+- `UserApp` 可选参数，默认为 `App.tsx` 导出的组件

package/docs/zh/apis/app/runtime/core/render.mdx

@@ -0,0 +1,43 @@
+---
+title: render
+---
+# render
+
+用于渲染项目组件。
+
+## 使用姿势
+
+```ts
+import { render } from '@modern-js/runtime/browser';
+
+render(<ModernRoot />);
+```
+
+## 函数签名
+
+```ts
+export function render(App: React.ReactElement, id?: HTMLElement | string): Promise<any>;
+```
+
+### 参数
+
+- `App`：通过 [`createRoot`](./create-root) 创建的 ReactElement 实例。
+- `id`：要挂载的 DOM 根元素 id，如 `"root"`。
+
+## 示例
+
+```tsx
+import { createRoot } from '@modern-js/runtime/react';
+import { render } from '@modern-js/runtime/browser';
+
+const ModernRoot = createRoot();
+
+async function beforeRender() {
+   // todo
+}
+
+beforeRender().then(() => {
+  render(<ModernRoot />);
+});
+```
+

package/docs/zh/apis/app/runtime/core/runtime-context.mdx

@@ -0,0 +1,160 @@
+---
+title: RuntimeContext
+---
+# RuntimeContext
+
+`RuntimeContext` 是一个 React Context，用于在组件中获取 Runtime 上下文信息。该 Context 可以通过 React 的 `use` 或 `useContext` API 访问。
+
+:::warning
+
+`useRuntimeContext` Hook 已废弃，请使用 `use(RuntimeContext)` 替代。`useRuntimeContext` 内部实现为 `useContext(RuntimeContext)`，而 `use(RuntimeContext)` 是 React 19 推荐的新方式。
+
+:::
+
+## 使用姿势
+
+```tsx
+import { use } from 'react';
+import { RuntimeContext } from '@modern-js/runtime';
+
+export function App() {
+  const runtimeContext = use(RuntimeContext); // 也可以使用 useContext(RuntimeContext)
+  return <div>Hello World</div>
+}
+```
+
+## 类型定义
+
+```ts
+type TRuntimeContext = {
+  initialData?: Record<string, unknown>;
+  isBrowser: boolean;
+  routes?: RouteObject[];
+  requestContext: RequestContext;
+  /**
+   * @deprecated Use `requestContext` instead
+   */
+  context: RequestContext;
+  [key: string]: unknown;
+};
+```
+
+### 属性说明
+
+- `isBrowser`：标识当前运行环境是否为浏览器
+- `routes`：路由配置信息
+- `requestContext`：请求上下文，包含 `request` 和 `response` 对象
+- `context`：已废弃，请使用 `requestContext` 替代
+
+### RequestContext
+
+`RequestContext` 是 `requestContext` 属性的类型，包含请求和响应相关的信息：
+
+```ts
+type RequestContext = {
+  request: {
+    params: Record<string, string>;      // 路由参数
+    pathname: string;                    // 路径名
+    query: Record<string, string>;       // 查询参数
+    headers: IncomingHttpHeaders;        // 请求头
+    host: string;                        // 主机名
+    url: string;                         // 完整 URL
+    referer?: string;                    // 来源页面
+    userAgent?: string;                  // 用户代理
+    cookie?: string;                     // Cookie 字符串
+    cookieMap?: Record<string, string>;  // Cookie 映射对象
+  };
+  response: {
+    setHeader: (key: string, value: string) => void;  // 设置响应头（仅服务端）
+    status: (code: number) => void;                    // 设置状态码（仅服务端）
+    locals: Record<string, any>;                       // 本地数据
+  };
+};
+```
+
+**注意事项**：
+
+- `response.setHeader` 和 `response.status` 仅在服务端（SSR）可用
+- 在浏览器端，`response` 对象可能不包含这些方法
+- `request` 对象在服务端和浏览器端都可用，但服务端信息更完整
+
+## 使用示例
+
+### 区分运行环境
+
+```tsx
+import { use } from 'react';
+import { RuntimeContext } from '@modern-js/runtime';
+
+function App() {
+  const { context, isBrowser } = use(RuntimeContext);
+
+  if (isBrowser === true) {
+    // 浏览器端执行逻辑
+    console.log('browser render')
+  } else {
+    // 服务器端执行逻辑
+    // 注意：logger 等功能需要通过 Runtime 插件注入到 context 中
+    console.log('server render')
+  }
+}
+```
+
+### 获取请求上下文
+
+开启 SSR 时，在 Node 环境和浏览器端环境可以获取到同构的请求上下文。
+
+稍有不同的是 Node 环境还支持设置响应头、响应码，并提供了 Logger 日志与 Metrics 打点。
+
+:::tip
+
+当 SSR 未开启时，仅包含可在浏览器端获取的部分信息。
+
+:::
+
+```tsx
+import { use } from 'react';
+import { RuntimeContext } from '@modern-js/runtime';
+
+function App() {
+  const runtimeContext = use(RuntimeContext);
+  const { request, response } = runtimeContext.requestContext || {};
+
+  // 访问请求信息
+  const userAgent = request?.userAgent || request?.headers?.['user-agent'];
+  const url = request?.url;
+  const query = request?.query;
+  const params = request?.params;
+
+  // 服务端可以设置响应头
+  if (!runtimeContext.isBrowser && response) {
+    response.setHeader('X-Custom-Header', 'value');
+    response.status(200);
+  }
+
+  return (
+    <div>
+      <div>User Agent: {userAgent}</div>
+      <div>URL: {url}</div>
+      <div>Query: {JSON.stringify(query)}</div>
+    </div>
+  );
+}
+```
+
+### 访问注入的全局数据
+
+通过 Runtime 插件的 `onBeforeRender` 钩子可以向 `RuntimeContext` 中注入全局数据：
+
+```tsx
+import { use } from 'react';
+import { RuntimeContext } from '@modern-js/runtime';
+
+export default function MyComponent() {
+  const context = use(RuntimeContext);
+  const { message } = context;
+
+  return <div>{message}</div>;
+}
+```
+