Add RSC Sandboxes (#8300)

* Add RSC Sandboxes

* Recover from errors, parse directives in worker with AST

* Fix client edits

* fast refresh

* hardening

* make rsc-sandbox-test dev-only

* add more examples to rsc-sandbox-test

* remove rsc-sandbox-text from sidebar

* Add inline server actions

* fix lint

* pin deps, update skill

* remove [RSC Client Error] from logs

* log error directly in worker

* update worker

Author: rickhanlonii

.claude/settings.json

@@ -16,6 +16,7 @@
       "Skill(docs-voice)",
       "Skill(docs-components)",
       "Skill(docs-sandpack)",
+      "Skill(docs-rsc-sandpack)",
       "Skill(docs-writer-learn)",
       "Skill(docs-writer-reference)",
       "Bash(yarn lint:*)",

.claude/skills/docs-rsc-sandpack/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: docs-rsc-sandpack
+description: Use when adding interactive RSC (React Server Components) code examples to React docs using <SandpackRSC>, or when modifying the RSC sandpack infrastructure.
+---
+
+# 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:
+
+```mdx
+<SandpackRSC>
+
+` ` `js src/App.js
+export default function App() {
+  return <h1>Hello from a Server Component!</h1>;
+}
+` ` `
+
+</SandpackRSC>
+```
+
+---
+
+## How It Differs from `<Sandpack>`
+
+| Feature | `<Sandpack>` | `<SandpackRSC>` |
+|---------|-------------|-----------------|
+| Execution model | All code runs in iframe | Server code runs in Web Worker, client code in iframe |
+| `'use client'` directive | Ignored (everything is client) | Required to mark client components |
+| `'use server'` directive | Not supported | Marks Server Functions callable from client |
+| `async` components | Not supported | Supported (server components can be async) |
+| External dependencies | Supported via `package.json` | Not supported (only React + react-dom) |
+| Entry point | `App.js` with `export default` | `src/App.js` with `export default` |
+| Component tag | `<Sandpack>` | `<SandpackRSC>` |
+
+---
+
+## File Directives
+
+Files are classified by the directive at the top of the file:
+
+| Directive | Where it runs | Rules |
+|-----------|--------------|-------|
+| (none) | Web Worker (server) | Default. Can be `async`. Can import other server files. Cannot use hooks, event handlers, or browser APIs. |
+| `'use client'` | Sandpack iframe (browser) | Must be first statement. Can use hooks, event handlers, browser APIs. Cannot be `async`. Cannot import server files. |
+| `'use server'` | Web Worker (server) | Marks Server Functions. Can be module-level (all exports are actions) or function-level. Callable from client via props or form `action`. |
+
+---
+
+## Common Patterns
+
+### 1. Server + Client Components
+
+```mdx
+<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
+
+```mdx
+<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)
+
+```mdx
+<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:
+
+| File | Purpose |
+|------|---------|
+| `/src/index.js` | Bootstraps the RSC pipeline |
+| `/src/rsc-client.js` | Client bridge — creates Worker, consumes Flight stream |
+| `/src/rsc-server.js` | Wraps pre-bundled worker runtime as ES module |
+| `/node_modules/__webpack_shim__/index.js` | Minimal webpack compatibility layer |
+| `/node_modules/__rsdw_client__/index.js` | `react-server-dom-webpack/client` as local dependency |
+
+### 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
+
+| File                                                            | Purpose                                                                        |
+|-----------------------------------------------------------------|--------------------------------------------------------------------------------|
+| `src/components/MDX/Sandpack/sandpack-rsc/RscFileBridge.tsx`    | Monitors Sandpack; posts raw files to iframe                                   |
+| `src/components/MDX/Sandpack/SandpackRSCRoot.tsx`               | SandpackProvider setup, custom bundler URL, UI layout                          |
+| `src/components/MDX/Sandpack/templateRSC.ts`                    | RSC template files                                                             |
+| `.../sandbox-code/src/__react_refresh_init__.js`                | React Refresh shim                                                             |
+| `.../sandbox-code/src/rsc-server.js`                            | Worker runtime: module system, Sucrase compilation, `renderToReadableStream()` |
+| `.../sandbox-code/src/rsc-client.source.js`                     | Client bridge: Worker creation, file classification, Flight stream consumption |
+| `.../sandbox-code/src/webpack-shim.js`                          | Minimal `__webpack_require__` / `__webpack_module_cache__` shim                |
+| `.../sandbox-code/src/worker-bundle.dist.js`                    | Pre-bundled IIFE (generated): React server + RSDW/server + Sucrase             |
+| `scripts/buildRscWorker.mjs`                                    | esbuild script: bundles rsc-server.js into worker-bundle.dist.js               |
+
+---
+
+## Build System
+
+### Rebuilding the Worker Bundle
+
+After modifying `rsc-server.js` or `webpack-shim.js`:
+
+```bash
+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
+
+```bash
+node scripts/buildRscWorker.mjs   # Rebuild worker bundle after source changes
+yarn dev                           # Start dev server to test examples
+```

.eslintignore

@@ -2,3 +2,4 @@ scripts
 plugins
 next.config.js
 .claude/
+worker-bundle.dist.js

package.json

@@ -6,7 +6,8 @@
   "scripts": {
     "analyze": "ANALYZE=true next build",
     "dev": "next-remote-watch ./src/content",
-    "build": "next build && node --experimental-modules ./scripts/downloadFonts.mjs",
+    "prebuild:rsc": "node scripts/buildRscWorker.mjs",
+    "build": "node scripts/buildRscWorker.mjs && next build && node --experimental-modules ./scripts/downloadFonts.mjs",
     "lint": "next lint && eslint \"src/content/**/*.md\"",
     "lint:fix": "next lint --fix && eslint \"src/content/**/*.md\" --fix",
     "format:source": "prettier --config .prettierrc --write \"{plugins,src}/**/*.{js,ts,jsx,tsx,css}\"",
@@ -38,6 +39,7 @@
     "next": "15.1.12",
     "next-remote-watch": "^1.0.0",
     "parse-numeric-range": "^1.2.0",
+    "raw-loader": "^4.0.2",
     "react": "^19.0.0",
     "react-collapsed": "4.0.4",
     "react-dom": "^19.0.0",
@@ -65,6 +67,7 @@
     "babel-eslint": "10.x",
     "babel-plugin-react-compiler": "^1.0.0",
     "chalk": "4.1.2",
+    "esbuild": "^0.24.0",
     "eslint": "7.x",
     "eslint-config-next": "12.0.3",
     "eslint-config-react-app": "^5.2.1",
@@ -88,6 +91,7 @@
     "postcss-flexbugs-fixes": "4.2.1",
     "postcss-preset-env": "^6.7.0",
     "prettier": "^2.5.1",
+    "react-server-dom-webpack": "^19.2.4",
     "reading-time": "^1.2.0",
     "remark": "^12.0.1",
     "remark-external-links": "^7.0.0",

scripts/buildRscWorker.mjs

@@ -0,0 +1,44 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import * as esbuild from 'esbuild';
+import fs from 'fs';
+import path from 'path';
+import {fileURLToPath} from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(__dirname, '..');
+const sandboxBase = path.resolve(
+  root,
+  'src/components/MDX/Sandpack/sandpack-rsc/sandbox-code/src'
+);
+
+// 1. Bundle the server Worker runtime (React server build + RSDW/server.browser + Sucrase → IIFE)
+// Minified because this runs inside a Web Worker (not parsed by Sandpack's Babel).
+const workerOutfile = path.resolve(sandboxBase, 'worker-bundle.dist.js');
+await esbuild.build({
+  entryPoints: [path.resolve(sandboxBase, 'rsc-server.js')],
+  bundle: true,
+  format: 'iife',
+  platform: 'browser',
+  conditions: ['react-server', 'browser'],
+  outfile: workerOutfile,
+  define: {'process.env.NODE_ENV': '"production"'},
+  minify: true,
+});
+
+// Post-process worker bundle:
+// Prepend the webpack shim so __webpack_require__ (used by react-server-dom-webpack)
+// is defined before the IIFE evaluates. The shim sets globalThis.__webpack_require__,
+// which is accessible as a bare identifier since globalThis IS the Worker's global scope.
+let workerCode = fs.readFileSync(workerOutfile, 'utf8');
+
+const shimPath = path.resolve(sandboxBase, 'webpack-shim.js');
+const shimCode = fs.readFileSync(shimPath, 'utf8');
+workerCode = shimCode + '\n' + workerCode;
+
+fs.writeFileSync(workerOutfile, workerCode);

src/components/MDX/MDXComponents.tsx

@@ -26,7 +26,7 @@ import BlogCard from './BlogCard';
 import Link from './Link';
 import {PackageImport} from './PackageImport';
 import Recap from './Recap';
-import Sandpack from './Sandpack';
+import {SandpackClient as Sandpack, SandpackRSC} from './Sandpack';
 import SandpackWithHTMLOutput from './SandpackWithHTMLOutput';
 import Diagram from './Diagram';
 import DiagramGroup from './DiagramGroup';
@@ -551,6 +551,7 @@ export const MDXComponents = {
   Recap,
   Recipes,
   Sandpack,
+  SandpackRSC,
   SandpackWithHTMLOutput,
   TeamMember,
   TerminalBlock,

src/components/MDX/Sandpack/Console.tsx

@@ -119,7 +119,7 @@ export const SandpackConsole = ({visible}: {visible: boolean}) => {
         setLogs((prev) => {
           const newLogs = message.log
             .filter((consoleData) => {
-              if (!consoleData.method) {
+              if (!consoleData.method || !consoleData.data) {
                 return false;
               }
               if (