docs-rsc-sandpack（文档 rsc 沙包）

RSC Sandpack Patterns

For general Sandpack conventions (code style, naming, file naming, line highlighting, hidden files, CSS guidelines), see /docs-sandpack. This skill covers only RSC-specific patterns.

Quick Start Template

Minimal single-file <SandpackRSC> example:

<SandpackRSC>

` ` `js src/App.js
export default function App() {
  return <h1>Hello from a Server Component!</h1>;
}
` ` `

</SandpackRSC>

How It Differs from <Sandpack>

File Directives

Files are classified by the directive at the top of the file:

Common Patterns

1. Server + Client Components

<SandpackRSC>

` ` `js src/App.js
import Counter from './Counter';

export default function App() {
  return (
    <div>
      <h1>Server-rendered heading</h1>
      <Counter />
    </div>
  );
}
` ` `

` ` `js src/Counter.js
'use client';

import { useState } from 'react';

export default function Counter() {
  const [count, setCount] = useState(0);
  return (
    <button onClick={() => setCount(count + 1)}>
      Count: {count}
    </button>
  );
}
` ` `

</SandpackRSC>

2. Async Server Component with Suspense

<SandpackRSC>

` ` `js src/App.js
import { Suspense } from 'react';
import Albums from './Albums';

export default function App() {
  return (
    <Suspense fallback={<p>Loading...</p>}>
      <Albums />
    </Suspense>
  );
}
` ` `

` ` `js src/Albums.js
async function fetchAlbums() {
  await new Promise(resolve => setTimeout(resolve, 1000));
  return ['Abbey Road', 'Let It Be', 'Revolver'];
}

export default async function Albums() {
  const albums = await fetchAlbums();
  return (
    <ul>
      {albums.map(album => (
        <li key={album}>{album}</li>
      ))}
    </ul>
  );
}
` ` `

</SandpackRSC>

3. Server Functions (Actions)

<SandpackRSC>

` ` `js src/App.js
import { addLike, getLikeCount } from './actions';
import LikeButton from './LikeButton';

export default async function App() {
  const count = await getLikeCount();
  return (
    <div>
      <p>Likes: {count}</p>
      <LikeButton addLike={addLike} />
    </div>
  );
}
` ` `

` ` `js src/actions.js
'use server';

let count = 0;

export async function addLike() {
  count++;
}

export async function getLikeCount() {
  return count;
}
` ` `

` ` `js src/LikeButton.js
'use client';

export default function LikeButton({ addLike }) {
  return (
    <form action={addLike}>
      <button type="submit">Like</button>
    </form>
  );
}
` ` `

</SandpackRSC>

File Structure Requirements

Entry Point

• src/App.js is required as the main entry point
• Must have export default (function component)
• Case-insensitive fallback: src/app.js also works

Auto-Injected Infrastructure Files

These files are automatically injected by sandpack-rsc-setup.ts and should never be included in MDX:

No External Dependencies

<SandpackRSC> does not support external npm packages. Only react and react-dom are available. Do not include package.json in RSC examples.

Architecture Reference

Three-Layer Architecture

react.dev page (Next.js)
  ┌─────────────────────────────────────────┐
  │  <SandpackRSC>                          │
  │  ┌─────────┐  ┌──────────────────────┐  │
  │  │ Editor  │  │ Preview (iframe)     │  │
  │  │ App.js  │  │ Client React app     │  │
  │  │ (edit)  │  │ consumes Flight      │  │
  │  │         │  │ stream from Worker   │  │
  │  └─────────┘  └──────────┬───────────┘  │
  └───────────────────────────┼─────────────┘
                              │ postMessage
  ┌───────────────────────────▼─────────────┐
  │  Web Worker (Blob URL)                  │
  │  - React server build (pre-bundled)     │
  │  - react-server-dom-webpack/server      │
  │  - webpack shim                         │
  │  - User server code (Sucrase → CJS)    │
  └─────────────────────────────────────────┘

Key Source Files

Build System

Rebuilding the Worker Bundle

After modifying rsc-server.js or webpack-shim.js:

node scripts/buildRscWorker.mjs

This runs esbuild with:

• format: 'iife', platform: 'browser'
• conditions: ['react-server', 'browser'] (activates React server export conditions)
• minify: true
• Prepends webpack-shim.js to the output

Raw-Loader Configuration

In templateRSC.js files are loaded as raw strings with the !raw-loader.

The strings are necessary to provide to Sandpack as local files (skips Sandpack bundling).

Development Commands

node scripts/buildRscWorker.mjs   # Rebuild worker bundle after source changes
yarn dev                           # Start dev server to test examples