第 07 讲｜Server / Client Components 的边界

              ┌──────────────────────┐
              │   server graph (rsc) │   ← Server Components 在这里
              │   ────────────────   │
              │   - 不可有 useState   │
              │   - 可以 fetch        │
              │   - 可以 import 任何   │
              │     server-only 代码 │
              └─────┬────────────────┘
                    │ 遇到 'use client'
                    │  (跨边界引用)
                    ▼
              ┌──────────────────────┐
              │  client graph (ssr +  │
              │   app-pages-browser)  │   ← Client Components 在这里
              │  ─────────────────   │
              │  - 可以 useState 等   │
              │  - 不能 import server-only │
              │  - 在 server 与 client 都跑│
              └──────────────────────┘

  reactServerComponents: 'rsc',
  /**
   * Server Side Rendering layer for app (ssr).
   */
  serverSideRendering: 'ssr',
  /**
   * The browser client bundle layer for actions.
   */
  actionBrowser: 'action-browser',
  /**
   * The Node.js bundle layer for the API routes.
   */
  apiNode: 'api-node',
  /**
   * The Edge Lite bundle layer for the API routes.
   */
  apiEdge: 'api-edge',
  /**
   * The layer for the middleware code.
   */
  middleware: 'middleware',
  /**
   * The layer for the instrumentation hooks.
   */
  instrument: 'instrument',
  /**
   * The layer for assets on the edge.
   */
  edgeAsset: 'edge-asset',
  /**
   * The browser client bundle layer for App directory.
   */
  appPagesBrowser: 'app-pages-browser',
  /**
   * The browser client bundle layer for Pages directory.
   */
  pagesDirBrowser: 'pages-dir-browser',

crates/next-custom-transforms/src/transforms/react_server_components.rs

/* __next_internal_client_entry_do_not_use__ default,Counter cjs */

export default function transformSource(
  this: LoaderContext<undefined>,
  source: string,
  sourceMap: any
) {
  // Avoid buffer to be consumed
  if (typeof source !== 'string') {
    throw new Error('Expected source to have been transformed to a string.')
  }
  const module = this._module!

  // Assign the RSC meta information to buildInfo.
  // Exclude next internal files which are not marked as client files
  const buildInfo = getModuleBuildInfo(module)
  buildInfo.rsc = getRSCModuleInformation(source, true)
  let prefix = ''
  if (process.env.BUILTIN_FLIGHT_CLIENT_ENTRY_PLUGIN) {
    const rscModuleInformationJson = JSON.stringify(buildInfo.rsc)
    prefix = `/* __rspack_internal_rsc_module_information_do_not_use__ ${rscModuleInformationJson} */\n`
    source = prefix + source
  }
  prefix += `// This file is generated by the Webpack next-flight-loader.\n`

  // Resource key is the unique identifier for the resource. When RSC renders
  // a client module, that key is used to identify that module across all compiler
  // layers.
  //
  // Usually it's the module's file path + the export name (e.g. `foo.js#bar`).
  // But with Barrel Optimizations, one file can be splitted into multiple modules,
  // so when you import `foo.js#bar` and `foo.js#baz`, they are actually different
  // "foo.js" being created by the Barrel Loader (one only exports `bar`, the other
  // only exports `baz`).
  //
  // Because of that, we must add another query param to the resource key to
  // differentiate them.
  let resourceKey: string = this.resourcePath
  if (module.matchResource?.startsWith(BARREL_OPTIMIZATION_PREFIX)) {
    resourceKey = formatBarrelOptimizedResource(
      resourceKey,
      module.matchResource
    )
  }

  // A client boundary.
  if (buildInfo.rsc?.type === RSC_MODULE_TYPES.client) {
    const assumedSourceType = getAssumedSourceType(
      module,
      sourceTypeFromModule(module)
    )

/* eslint-disable import/no-extraneous-dependencies */
import { createClientModuleProxy } from 'react-server-dom-webpack/server'

// Re-assign to make it typed.
export const createProxy: (moduleId: string) => any = createClientModuleProxy

export function isClientReference(mod: any): boolean {
  const defaultExport = mod?.default || mod
  return defaultExport?.$$typeof === Symbol.for('react.client.reference')
}

src/build/webpack/plugins/flight-client-entry-plugin.ts

你的代码 hello-button.tsx
    ↓ SWC parse
检测到 'use client' → metadata 注入
    ↓
   ┌─────────────────────────┬─────────────────────────┐
   ▼ rsc layer               ▼ ssr layer               ▼ app-pages-browser layer
next-flight-loader          原样保留                   原样保留
替换为 createProxy           （SSR 跑这份）             （hydration 跑这份）
    ↓                        ↓                          ↓
server graph 中：           server graph 中：          client bundle 中：
import HelloButton          import HelloButton         作为新的 entry
=> { $$typeof, $$id }       => 真正的 React 组件       (.next/static/chunks/...)
                            (用于 SSR 渲染初始 HTML)
                            ↓
                            写到 client-reference-manifest

// app/layout.tsx
import { createContext, useState } from "react"; // ← server component 不能 import 这个！

const ThemeContext = createContext("light");

export default function RootLayout({ children }) {
  const [theme, setTheme] = useState("light"); // ← 报错：useState in Server Component
  return (
    <ThemeContext.Provider value={theme}>
      <html>
        <body>{children}</body>
      </html>
    </ThemeContext.Provider>
  );
}

// app/_components/theme-provider.tsx
"use client";
import { createContext, useContext, useState } from "react";

const ThemeContext = createContext<{
  theme: string;
  toggle: () => void;
} | null>(null);

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setTheme] = useState("light");
  return (
    <ThemeContext.Provider
      value={{
        theme,
        toggle: () => setTheme((t) => (t === "light" ? "dark" : "light")),
      }}
    >
      {children}
    </ThemeContext.Provider>
  );
}

export function useTheme() {
  const ctx = useContext(ThemeContext);
  if (!ctx) throw new Error("useTheme must be used inside ThemeProvider");
  return ctx;
}

// app/layout.tsx  (server component)
import { ThemeProvider } from "./_components/theme-provider";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}

// app/some-page.tsx (server component)
import { toast, ToastContainer } from "react-toastify"; // ← 错！server 跑会报 window is not defined

export default function Page() {
  return <ToastContainer />;
}

// app/_components/toast-container-client.tsx
"use client";
export { toast, ToastContainer } from "react-toastify";
import "react-toastify/dist/ReactToastify.css";

// app/some-page.tsx (server component)
import { ToastContainer } from "../_components/toast-container-client";

export default function Page() {
  return <ToastContainer />;
}

"use client";
import dynamic from "next/dynamic";
export const Toaster = dynamic(
  () => import("react-toastify").then((m) => m.ToastContainer),
  {
    ssr: false, // 完全跳过 SSR pass
  },
);

// app/products/page.tsx (server)
import { ProductDetail } from "./product-detail"; // client component

class Product {
  constructor(
    public id: string,
    public name: string,
  ) {}
  formatName() {
    return this.name.toUpperCase();
  }
}

export default function Page() {
  const p = new Product("001", "Widget");
  return <ProductDetail product={p} />; // ← 错！class 实例无法序列化
}

return <ProductDetail product={{ id: p.id, name: p.name }} />;

return <ProductDetail id={p.id} name={p.name} />;

// app/orders/page.tsx (server)
async function cancelOrder(id: string) {
  "use server";
  // ... DB delete
}

return <OrderRow order={order} onCancel={cancelOrder} />; // OK

"use client";
import { getUserData } from "../server-data"; // ← 错，假设 server-data.ts 是 server-only

export function Profile() {
  const [data, setData] = useState(null);
  useEffect(() => {
    getUserData("123").then(setData); // 直接在 client 里调 server 函数
  }, []);
}

// app/_actions/get-user-data.ts
"use server";
export async function getUserData(id: string) {
  // ... fetch DB
  return { id, name: "Alice" };
}

"use client";
import { getUserData } from "../_actions/get-user-data";
// 这次 import 拿到的是 server reference proxy
// 调用它 = 发 POST 到 server

// app/profile/page.tsx (server)
import { getUserData } from "./data";
import { Profile } from "./profile-client";

export default async function Page() {
  const data = await getUserData("123");
  return <Profile data={data} />;
}

// app/_components/query-provider.tsx
"use client";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { useState } from "react";

export function QueryProvider({ children }: { children: React.ReactNode }) {
  const [client] = useState(() => new QueryClient());
  return <QueryClientProvider client={client}>{children}</QueryClientProvider>;
}

// app/layout.tsx (server)
import { QueryProvider } from "./_components/query-provider";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <QueryProvider>{children}</QueryProvider>
      </body>
    </html>
  );
}

// app/account/page.tsx (server)
import { cookies } from "next/headers";
import { getUserByToken } from "./data";

export default async function AccountPage() {
  const cookieStore = await cookies();
  const token = cookieStore.get("session")?.value;
  const user = await getUserByToken(token);
  return <p>欢迎 {user.email}</p>;
}

"use client";
import { cookies } from "next/headers"; // ← 编译期报错

import "server-only"; // 在 client layer 编译会失败

- 文件路径在 app/* 下，且文件顶部有 'use client' → 进入 ssr & app-pages-browser
- app/* 下其他文件 → 进入 rsc layer
- 文件路径含 server-only 包 → 仅 rsc layer，client layer require 报错

cd fixtures/lecture-07
pnpm dev

# 另一个 terminal
curl -s -H 'RSC: 1' http://localhost:3007/example-1-context?_rsc=1 | head -40

1:I["./app/_components/theme-provider.tsx",["app/example-1-context/page",...],""]
0:["$","$L1",null,{children:[...]}]

"use server";
export const MY_CONSTANT = 42; // ← 错！server action file 只能 export 函数
export async function doIt() {
  /* ... */
}

function MyClientFn() {
  "use client"; // ← 错，directive 必须在文件顶部
  // ...
}

A.tsx (server)
 └─ imports B.tsx ('use client')
     └─ imports C.tsx (no directive)