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

package/docs/zh/guides/basic-features/render/rsc.mdx

@@ -0,0 +1,399 @@
+---
+title: React Server Components (RSC)
+---
+
+# React Server Components (RSC)
+
+React Server Components (RSC) 是一种新的组件类型，允许在服务端环境中渲染组件，为现代 Web 应用带来更好的性能和开发体验。
+
+## 核心优势
+
+- **零客户端 JavaScript**：Server Components 的代码不会被打包到客户端，显著减少客户端 bundle 体积
+- **直接访问服务端资源**：可以直接访问数据库、文件系统、内部 API 等服务端资源，无需额外的 API 层
+- **更好的性能**：数据获取更接近数据源，减少客户端数据瀑布流，提升首屏加载速度
+- **自动代码分割**：基于实际渲染的数据进行代码分割，而不仅仅是路由，实现更精细的代码优化
+- **更高的内聚性**：与数据、权限、缓存等紧密相关的逻辑可以留在 Server Component 中，组件内聚度更高，减少状态上浮和跨层级传递
+
+:::tip 前置阅读
+在开始之前，建议你阅读 React 官方的 [Server Components 文档](https://react.dev/reference/rsc/server-components)，对 Server Component 有一个基本的了解。
+
+:::
+
+## 快速开始
+
+1. **确保 React 和 React DOM 升级到 19 版本**（建议 19.2.3 以上版本）
+
+2. **安装 `react-server-dom-webpack` 依赖**
+
+```bash
+npm install react-server-dom-webpack
+```
+
+:::warning 注意事项
+
+1. 目前暂不支持在 SPA 项目中使用 [Server Functions](https://react.dev/reference/rsc/server-functions)
+2. 目前在 Rspack 构建时，产物分片和体积还未达到最优状态，我们将在近期进一步优化
+
+:::
+
+3. 设置 [`server.rsc`](/configure/app/server/rsc) 为 `true`：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    rsc: true,
+  },
+});
+```
+
+:::info 旧 CSR 项目迁移
+如果是 CSR 项目，且项目中使用了 Modern.js 的 data loader，开启 RSC 后，data loader 默认会在服务端执行。
+为了与原有行为保持一致，需要先将所有的 `.data.ts` 文件改为 `.data.client.ts`。
+
+:::
+
+## 使用指南
+
+### 默认行为
+
+默认情况下，当开启 RSC 时，Modern.js 中的所有组件默认是 **Server Component**。Server Component 允许你在服务端获取数据并渲染 UI。当需要交互性（如事件处理、状态管理）或使用浏览器 API 时，你可以使用 `"use client"` 指令将组件标记为 **Client Component**。
+
+### 组件类型选择
+
+#### 何时使用 Client Component
+
+当组件需要以下功能时，你需要使用 `"use client"` 指令将其标记为 Client Component：
+
+- **交互性**：使用 [State](https://react.dev/learn/managing-state) 和 [event handlers](https://react.dev/learn/responding-to-events)，例如 `onClick`、`onChange`、`onSubmit`
+- **生命周期**：使用[生命周期](https://react.dev/learn/lifecycle-of-reactive-effects)相关的 hook，例如 `useEffect`、`useLayoutEffect`
+- **浏览器 API**：使用浏览器的 API（如 `window`、`document`、`localStorage`、`navigator` 等）
+- **自定义 Hook**：使用[自定义 hook](https://react.dev/learn/reusing-logic-with-custom-hooks)，特别是那些依赖客户端特性的 hook
+
+#### 何时使用 Server Component
+
+以下场景应该使用 Server Component（默认行为，无需额外标记）：
+
+1. **访问服务端资源**：使用服务端才有的 API（如 Node.js 的 API、文件系统、consul、RPC 等）
+2. **数据获取**：在服务端获取数据以优化性能，减少客户端请求
+3. **安全性**：访问私密的环境变量或 API 密钥，避免暴露给客户端
+4. **减少 bundle 体积**：使用大型依赖库，这些库不需要包含在客户端 bundle 中
+5. **静态内容**：渲染静态或变化频率低的内容
+
+### Client Boundary（客户端边界）
+
+一旦一个文件被标记为 `"use client"`，那么它所导入的所有其他模块（如果它们还没有被标记为 `"use client"`）也会被认为是客户端代码，并被包含在客户端的 JavaScript 包中。这就是 **Client Boundary** 的概念。
+
+:::tip 理解 Client Boundary
+`"use client"` 指令创建了一个边界：边界内的所有代码都会被打包到客户端。这意味着即使 `Button` 和 `Tooltip` 组件本身没有 `"use client"` 指令，它们也会因为被 `InteractiveCard` 导入而成为客户端代码。
+
+:::
+
+```tsx title="components/InteractiveCard.tsx"
+'use client'; // <--- 这里是 Client Boundary 的起点
+
+import { useState } from 'react';
+import Button from './Button'; // Button.tsx 没有 "use client"，但会被包含在客户端 bundle 中
+import Tooltip from './Tooltip'; // Tooltip.tsx 也没有 "use client"，同样会被包含
+
+export default function InteractiveCard() {
+  const [isActive, setIsActive] = useState(false);
+
+  return (
+    <div onClick={() => setIsActive(!isActive)}>
+      <p>Click me!</p>
+      <Button />
+      <Tooltip text="This is a card" />
+    </div>
+  );
+}
+```
+
+### 如何组合两种组件
+
+Server Component 和 Client Component 并非孤立存在，它们需要协同工作。请记住以下两条规则：
+
+#### Server Component 可以导入 Client Component
+
+这是最常见的模式，你的页面主体是一个 Server Component，负责获取数据和布局，而在其中需要交互的部分，则嵌入 Client Component。
+
+```tsx title="routes/page.tsx"
+// Server Component（默认，无需标记）
+import CounterButton from './CounterButton'; // 这是一个 Client Component
+
+async function getPageData() {
+  // 在服务端获取数据
+  const res = await fetch('https://api.example.com/data');
+  return res.json();
+}
+
+export default async function Page() {
+  const data = await getPageData();
+
+  return (
+    <div>
+      <h1>{data.title}</h1> {/* 服务端渲染 */}
+      <p>This part is static.</p>
+      {/* Client Component 可以无缝嵌入 Server Component */}
+      <CounterButton />
+    </div>
+  );
+}
+```
+
+```tsx title="routes/CounterButton.tsx"
+'use client'; // Client Component
+
+import { useState } from 'react';
+
+export default function CounterButton() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>;
+}
+```
+
+#### Client Component 不能直接导入 Server Component
+
+这一点初看起来可能有些违反直觉。原因在于：Server Component 的代码根本不存在于客户端。当一个 Client Component 在浏览器中渲染时，它无法去执行一个只存在于服务器上的函数。
+
+但是，有两种模式可以绕过这个限制：
+
+**1. 通过 `children` Prop 传递 Server Component**
+
+你可以将 Server Components 作为 `children` Prop 传递给一个 Client Component。假设一个带动画的 Tabs 组件，Tabs 的切换逻辑本身是客户端的，但每个标签页的内容可能是静态的、从服务器获取的。
+
+```tsx title="app/components/Tabs.tsx"
+'use client'; // Client Component
+
+import React, { useState } from 'react';
+
+interface TabsProps {
+  tabLabels: string[];
+  children: React.ReactNode;
+}
+
+export default function Tabs({ tabLabels, children }: TabsProps) {
+  const [activeTab, setActiveTab] = useState(0);
+
+  return (
+    <div>
+      <nav>
+        {tabLabels.map((label, index) => (
+          <button key={label} onClick={() => setActiveTab(index)}>
+            {label}
+          </button>
+        ))}
+      </nav>
+      {/* React.Children.toArray 会确保只渲染活跃的子组件 */}
+      <div>{React.Children.toArray(children)[activeTab]}</div>
+    </div>
+  );
+}
+```
+
+```tsx title="app/dashboard/page.tsx"
+// Server Component（默认）
+import Tabs from '../components/Tabs';
+import Analytics from '../components/Analytics'; // Server Component
+import UserSettings from '../components/UserSettings'; // Server Component
+
+export default function DashboardPage() {
+  const labels = ['Analytics', 'Settings'];
+
+  return (
+    <main>
+      <h1>Dashboard</h1>
+      {/*
+        这里，Tabs 是 Client Component（负责交互逻辑），
+        但 Analytics 和 UserSettings 是在服务端渲染好的 Server Component，
+        它们作为 children prop 传递给 Tabs 组件。
+        这样既保持了交互性，又最大化利用了服务端渲染的优势。
+      */}
+      <Tabs tabLabels={labels}>
+        <Analytics />
+        <UserSettings />
+      </Tabs>
+    </main>
+  );
+}
+```
+
+通过这种模式，你可以在保持交互性的同时，最大限度地将组件保留在服务端，从而获得极致的性能。这是 RSC 中最强大的组合模式之一。
+
+**2. 路由组件可以独立选择组件类型**
+
+每一级的路由组件（如 `layout.tsx`、`page.tsx`）可以独立选择是 Client Component 还是 Server Component：
+
+```bash
+- routes
+    - layout.tsx  // 可以是 Client Component
+    - page.tsx    // 可以是 Server Component
+```
+
+例如，假设 `layout.tsx` 是一个 Client Component（需要客户端交互），你仍然可以将 `page.tsx` 设置为 Server Component（用于数据获取和渲染）。这种方式提供了极大的灵活性，也使非 RSC 项目可以渐进式地迁移至 RSC 项目。
+
+## 注意事项
+
+### 旧 CSR 项目
+
+如果是 CSR 项目，且项目中使用了 EdenX 的 data loader，开启 RSC 后，data loader 默认是在服务端执行，这意味着需要先把所有的 `.data.ts` 文件改为`.data.client.ts`，才能和之前的行为保持一致。
+
+### 使用 Streaming SSR 的项目
+
+如果你同时使用了 Streaming SSR 和 RSC，在 react19 中需要通过使用 `use`，而不再需要使用 `Await` 组件：
+
+```ts
+function NonCriticalUI({ p }: { p: Promise<string> }) {
+  let value = React.use(p);
+  return <h3>Non critical value {value}</h3>;
+}
+
+<React.Suspense fallback={<div>Loading...</div>}>
+  <NonCriticalUI p={nonCriticalData} />
+</React.Suspense>
+```
+
+## 最佳实践
+
+### 获取数据
+
+1. 不管是 SSR 还是 RSC 项目，建议在服务端执行的数据获取逻辑默认使用 Modern.js 提供的 `cache` 函数，这样每一次服务端渲染，不管调用该函数多少次，只会执行一次。
+
+> 这也是 react.js 推荐的用法，为此 react.js 提供了 [cache](https://react.dev/reference/react/cache), Modern.js 的 [cache](/guides/basic-features/data/data-cache.html) 可以视作其超集。
+
+```typescript
+import { cache } from '@modern-js/runtime/cache';
+
+const getCriticalCached = cache(getCritical);
+```
+
+- 在使用 `cache` 函数的基础上，你不再需要通过 `props`，`context` 等管理服务端的状态，我们推荐哪个组件需要数据就在最近的 Server Component 中获取数据，通过 cache 函数，即使多次调用同一个函数，这样可以使项目的状态管理，业务逻辑，性能优化更简单。
+
+```typescript
+// layout.tsx
+export default async function Layout() {
+  const criticalData = await getCriticalCached();
+}
+
+export default async function Page() {
+  const criticalData = await getCriticalCached();
+}
+```
+
+### 最佳性能
+
+为了发挥 RSC 或 Streaming SSR 的优势，我们需要使尽可能多的组件流动起来，一个核心原则是使 Suspense 包裹的区域尽可能地小（这也是我们推荐使用 `cache` 函数的原因之一）
+
+对于直接消费数据的 Server Component，我们推荐在其上层包裹 Suspense：
+
+> 这种场景下 Server Component 往往是异步的，还有一种情况 Server Component 为同步的，由 Client Component 消费数据，在下面进行描述
+
+```javascript
+// profile/components/PostsList.tsx
+export default async function PostsList() {
+  const posts = await getUserPosts();
+
+  return (
+    <ul>
+      {posts.map(post => (
+        <li key={post.id}>{post.title}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+```javascript
+// profile/page.tsx
+import { Suspense } from 'react';
+import UserInfo from './components/UserInfo';
+import PostsList from './components/PostsList';
+import PostsSkeleton from './components/PostsSkeleton';
+
+export default function ProfilePage() {
+  return (
+    <div>
+      <UserInfo />
+
+      <hr />
+
+      {/*
+        我们将慢速的 PostsList 包裹在 Suspense 中。
+        当 PostsList 正在获取数据时，用户会看到 PostsSkeleton。
+        一旦 PostsList 的数据准备就绪，它会自动替换掉骨架屏。
+      */}
+      <Suspense fallback={<PostsSkeleton />}>
+        <PostsList posts={postsPromise} />
+      </Suspense>
+    </div>
+  );
+}
+```
+
+还有一种场景是在 Client Component 中消费数据，此时我们应避免在 Server Component 中使用 `await`，避免阻塞渲染：
+
+```javascript
+// profile/components/PostsList.tsx
+'use client';
+export default function PostsList({ postsPromise }) {
+  const posts = use(postsPromise);
+
+  return (
+    <ul>
+      {posts.map(post => (
+        <li key={post.id}>{post.title}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+```javascript
+// profile/page.tsx
+import { Suspense } from 'react';
+import UserInfo from './components/UserInfo';
+import PostsList from './components/PostsList'; // 现在是 Client Component
+import PostsSkeleton from './components/PostsSkeleton';
+import { getUserPosts } from '../lib/data'; // 导入数据获取函数
+
+// 注意：这个组件不是 async 的
+export default function ProfilePage() {
+  // 1. 在服务端调用数据获取函数，但不 await 它
+  // 这会立即返回一个 Promise
+  const postsPromise = getUserPosts();
+
+  return (
+    <div>
+      <UserInfo />
+
+      <hr />
+
+      {/* 2. Suspense 边界依然是必需的。它会捕获
+          由 PostsList 内部的 `use` 钩子抛出的 Promise */}
+      <Suspense fallback={<PostsSkeleton />}>
+        {/* 3. 将 Promise 对象本身作为 prop 传递给客户端组件 */}
+        <PostsList postsPromise={postsPromise} />
+      </Suspense>
+    </div>
+  );
+}
+```
+
+### Helmet
+
+当使用 react19 时，无需再使用 Helmet，推荐直接使用 react 提供的[组件](https://react.dev/reference/react-dom/components)。
+
+## 常见问题
+
+### `This entry point is not yet supported outside of experimental channels`
+
+项目中的 bundle 引入了非 19 的 react 版本，常见于 monorepo。请确保所有依赖都使用 React 19 版本。
+
+## 相关链接
+
+- [React Server Components 官方文档](https://react.dev/reference/rsc/server-components)
+- [React Server Functions 文档](https://react.dev/reference/rsc/server-functions)
+- [数据缓存](/guides/basic-features/data/data-cache)
+- [服务端渲染（SSR）](/guides/basic-features/render/ssr)
+- [Streaming SSR](/guides/basic-features/render/streaming-ssr)

package/docs/zh/guides/basic-features/render/ssg.mdx

@@ -8,25 +8,9 @@ SSG（Static Site Generation）是一种基于数据与模板，在构建时渲
 
 ## 启用 SSG
 
-我们首先需要执行 `pnpm run new` 启用 SSG 功能：
+import EnableSSG from '@site-docs/components/enable-ssg';
 
-```bash
-? 请选择你想要的操作 启用可选功能
-? 请选择功能名称 启用「SSG」功能
-```
-
-执行命令后，在 `modern.config.ts` 中注册 SSG 插件：
-
-```ts title="modern.config.ts"
-import { ssgPlugin } from '@modern-js/plugin-ssg';
-
-export default defineConfig({
-  output: {
-    ssg: true,
-  },
-  plugins: [..., ssgPlugin()],
-});
-```
+<EnableSSG />
 
 ## 开发环境调试
 
@@ -67,7 +51,7 @@ export default defineConfig({
 - `/user/profile`
 
 :::tip
-如果还不了解约定式路由的规则，可以先查看[路由方案](/guides/basic-features/routes)。
+如果还不了解约定式路由的规则，可以先查看[路由方案](/guides/basic-features/routes/routes)。
 
 :::
 
@@ -87,37 +71,6 @@ export default () => {
 
 执行 `pnpm run serve` 启动项目后，访问页面，在浏览器我们工具的 Network 窗口，查看请求返回的文档，文档包含组件渲染后的完整页面内容。
 
-### 阻止默认行为
-
-默认情况下，**约定式路由**的路由会全部开启 SSG。Modern.js 提供了另一个字段，用来阻止默认的 SSG 行为。
-
-例如以下目录结构，`/`、`/user`、`/user/profle` 三条路由都开启 SSG：
-
-```bash
-.
-├── src
-│   └── routes
-│       ├── layout.tsx
-│       ├── page.tsx
-│       └── user
-│           ├── layout.tsx
-│           ├── page.tsx
-│           └── profile
-│               └── page.tsx
-```
-
-可以通过配置 `preventDefault` 来禁用某些路由的默认行为。进行下面配置后，最终只会生成 `/`、`/user/profle` 两条路由的 SSG 页面：
-
-```js
-export default defineConfig({
-  output: {
-    ssg: {
-      preventDefault: ['/user'],
-    },
-  },
-});
-```
-
 ## 在自控式路由中使用
 
 **自控式路由**是通过组件代码定义路由，需要应用运行起来才能获取准确的路由信息。因此，无法开箱即用的使用 SSG 功能。开发者需要通过配置告知 Modern.js 框架，哪些路由需要开启 SSG 功能。
@@ -148,35 +101,40 @@ export default defineConfig({
 以上仅介绍了单入口的情况，更多相关内容可以查看 [API 文档](/configure/app/output/ssg)。
 :::
 
-## 添加路由参数
-
-在 Modern.js 中，部分路由可能是动态的，例如自控式路由中的 `/user/:id` 或是约定式路由中 `user/[id]/page.tsx` 文件生成的路由。
+## 添加动态路由
 
-可以在 `output.ssg` 中配置具体的参数，渲染指定参数的路由，例如：
+在自控式路由或包含动态段的约定式路由（如 `/user/[id]`）中，直接在 `routes` 中写入具体路径。
 
 ```js
 export default defineConfig({
   output: {
     ssg: {
-      routes: [
-        {
-          url: '/user/:id',
-          params: [{
-            id: 'modernjs',
-          }],
-        },
-      ],
+      routes: ['/', '/about', '/user/modernjs'],
     },
   },
 });
 ```
 
-此时，`/user/modernjs` 路由会被渲染，并且在渲染时，会将 `id` 参数传递给组件。当配置多个值时，对应会生成多张页面。
+## 多入口
 
-:::note
-动态路由和 SSG 的组合，在根据 CMS 系统数据变更，实时生成静态页面时非常有用。
-:::
+多入口应用请通过 `output.ssgByEntries` 按入口分别配置：
 
+```js
+export default defineConfig({
+  output: {
+    ssgByEntries: {
+      home: {
+        routes: ['/', '/about', '/user/modernjs'],
+      },
+      admin: false,
+    },
+  },
+});
+```
+
+:::info
+详细配置请参考：[output.ssgByEntries](/configure/app/output/ssgByEntries)
+:::
 
 ## 配置渲染请求头
 
@@ -187,14 +145,14 @@ export default defineConfig({
   output: {
     ssg: {
       headers: {
-        "x-tt-env": "ppe_modernjs"
+        'x-tt-env': 'ppe_modernjs',
       },
       routes: [
         '/',
         {
           url: '/about',
           headers: {
-            "from": "modern-website"
+            from: 'modern-website',
           },
         },
       ],
@@ -207,4 +165,4 @@ export default defineConfig({
 
 :::tip
 路由中设置的 `headers` 会覆盖入口中设置的 `headers`。
-:::
+:::

package/docs/zh/guides/basic-features/render/ssr-cache.mdx

@@ -8,16 +8,12 @@ title: 渲染缓存
 
 Modern.js 支持将服务器端渲染（SSR）结果进行缓存，减少服务器每次请求时的计算和渲染时间，从而加速页面加载速度，提高用户体验。同时，缓存也能降低服务端负载，节省计算资源，提高用户访问速度。
 
-:::tip
-需要 x.43.0+
-:::
-
 ## 配置方式
 
 在应用中创建 `server/cache.[t|j]s` 文件，并导出 `cacheOption` 配置缓存即可开启 SSR 渲染缓存：
 
 ```ts title="server/cache.ts"
-import type { CacheOption } from '@modern-js/runtime/server';
+import type { CacheOption } from '@modern-js/server-runtime';
 
 export const cacheOption: CacheOption = {
   maxAge: 500, // ms
@@ -57,7 +53,7 @@ export type CacheOptionProvider = (
 
 ```ts title="server/cache.ts"
 
-import type { CacheOption, CacheOptionProvider } from '@modern-js/runtime/server';
+import type { CacheOption, CacheOptionProvider } from '@modern-js/server-runtime';
 
 const provider: CacheOptionProvider = (req) => {
   const { url, headers, ... } = req;
@@ -85,7 +81,7 @@ export type CacheOptions = Record<string, CacheControl | CacheOptionProvider>;
 有时开发者面对不同的路由需要应用不同的缓存策略。我们也提供一种映射的方式进行配置, 以下列代码为例：
 
 ```ts title="server/cache.ts"
-import type { CacheOption } from '@modern-js/runtime/server';
+import type { CacheOption } from '@modern-js/server-runtime';
 
 export const cacheOption: CacheOption = {
   '/home': {
@@ -151,7 +147,7 @@ export interface Container<K = string, V = string> {
 以下面代码为例，开发者可实现一个 redis 缓存容器。
 
 ```ts
-import type { Container, CacheOption } from '@modern-js/runtime/server';
+import type { Container, CacheOption } from '@modern-js/server-runtime';
 
 class RedisContainer implements Container {
   redis = new Redis();
@@ -206,4 +202,4 @@ export const cacheOption: CacheOption = {
 | hit     | 缓存命中，返回缓存内容                             |
 | stale   | 缓存命中，但数据陈旧，返回缓存内容的同时做重新渲染 |
 | expired | 缓存命中，重新渲染后返回渲染结果                   |
-| miss    | 缓存未命中                                         |
+| miss    | 缓存未命中                                         |