docs: address RSC pitfalls review follow-ups (#3155)

justin808 · claude · justin808 · commit fb5bc4fbba3f · 2026-04-17T16:16:38.000-10:00
Applies the documentation review comments surfaced against PR #3087: - Add missing `runs-on: ubuntu-latest` to the CI workflow example in node-renderer/basics.md so the snippet is copy-paste valid. - Correct the `resolve.fallback: false` inline comment in rsc-troubleshooting.md to match the surrounding explanation ("omit the module" rather than "provide empty modules"). - Expand the upgrading-existing-pro-app audit checklist to include the React, React DOM, router, and ReactOnRails hook names that were listed in "What to look for" but missing from the checklist. - Reorder the MessageChannel troubleshooting section to lead with the recommended `additionalContext` fix and demote BannerPlugin to a fallback, so users encounter the preferred option first. - Clarify `fetch` under "Browser APIs": it is a Node.js global since v18 and works in Server Components; only flag it when called inside a `useEffect` (already covered by the hooks list). Fixes #3155 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
diff --git a/docs/oss/building-features/node-renderer/basics.md b/docs/oss/building-features/node-renderer/basics.md
@@ -157,6 +157,7 @@ The Node Renderer must be started as a background process before running tests.
 # .github/workflows/test.yml (GitHub Actions example)
 jobs:
   test:
+    runs-on: ubuntu-latest
     env:
       # Job-level: both the renderer and Rails test steps need this
       RENDERER_PASSWORD: ${{ secrets.RENDERER_PASSWORD }}
diff --git a/docs/oss/migrating/rsc-troubleshooting.md b/docs/oss/migrating/rsc-troubleshooting.md
@@ -863,7 +863,7 @@ externals: {
 **Correct approach:**
 
 ```js
-// In serverWebpackConfig.js -- tells webpack to provide empty modules
+// In serverWebpackConfig.js -- tells webpack to omit these modules (no require() call emitted)
 resolve: {
   fallback: {
     path: false,
@@ -881,7 +881,19 @@ resolve: {
 
 **Root cause:** `react-dom/server.browser.js` (used for SSR streaming) instantiates `MessageChannel` at **module load time** for React's internal scheduler. The VM sandbox does not provide `MessageChannel` as a global, and `supportModules` does not include it.
 
-**Fix:** Use webpack's `BannerPlugin` to inject a minimal `MessageChannel` polyfill at the top of the server bundle. The polyfill only needs to support `port2.postMessage` triggering `port1.onmessage`, which is all React's scheduler requires:
+**Fix (recommended):** Use `additionalContext` in the node renderer config to inject Node.js' native `MessageChannel` into the VM sandbox. Node.js has had a native `MessageChannel` since Node 15, and passing it through `additionalContext` gives React's scheduler correct async scheduling (macrotask delivery), which is what it depends on:
+
+```js
+// In your node-renderer.js config
+const { MessageChannel } = require('node:worker_threads');
+
+const config = {
+  // ... other options
+  additionalContext: { MessageChannel },
+};
+```
+
+**Fallback:** If you cannot change the renderer config (e.g., a build-only setup without renderer config control), inject a minimal `MessageChannel` polyfill at the top of the server bundle using webpack's `BannerPlugin`. The polyfill only needs to support `port2.postMessage` triggering `port1.onmessage`, which is all React's scheduler requires:
 
 ```js
 // In serverWebpackConfig.js
@@ -914,9 +926,7 @@ plugins: [
 ];
 ```
 
-This injects the polyfill as raw JavaScript at the top of the bundle output, ensuring `MessageChannel` is defined before any module code executes.
-
-**Recommended approach:** Use `additionalContext` in the renderer config to inject Node.js' native `MessageChannel` into the VM sandbox. This provides correct async scheduling (macrotask delivery), which React's scheduler depends on. The `BannerPlugin` polyfill above delivers messages synchronously — this works for current SSR streaming scenarios but may cause subtle rendering bugs if React yields mid-render and re-enters the scheduler.
+This injects the polyfill as raw JavaScript at the top of the bundle output, ensuring `MessageChannel` is defined before any module code executes. Note: this polyfill delivers messages synchronously, which works for current SSR streaming scenarios but may cause subtle rendering bugs if React yields mid-render and re-enters the scheduler. Prefer the `additionalContext` approach above whenever possible.
 
 > **When to use the `BannerPlugin` polyfill:** Use it only when the renderer config's `additionalContext` is not accessible (e.g., in a build-only setup without renderer config control). If you encounter recursive stack-overflow errors or unexpected rendering behavior with the synchronous polyfill, switch to the `additionalContext` approach.
 
diff --git a/docs/pro/react-server-components/upgrading-existing-pro-app.md b/docs/pro/react-server-components/upgrading-existing-pro-app.md
@@ -45,7 +45,7 @@ Components that use any of the following **must** have `'use client'`:
 - **Router client APIs**: `useNavigate`, `useLocation`, `useParams`
 - **SSR entry-point files** using `StaticRouter`: these are SSR wrappers, not RSC server components — see the `.server.jsx` naming collision below
 - **Event handlers**: `onClick`, `onChange`, `onSubmit`, etc.
-- **Browser APIs**: `window`, `document`, `localStorage`, `fetch` in effects
+- **Browser APIs**: `window`, `document`, `localStorage` (note: `fetch` is a Node.js global since v18 and works in Server Components — calling it directly in server context is an encouraged RSC pattern; only flag `fetch` if it is called inside a `useEffect`, which is already covered by the hooks list above)
 
 ### The `.server.jsx` naming collision
 
@@ -71,7 +71,7 @@ There is no warning when a component is auto-classified as a server component. I
 
 Before proceeding to Step 1:
 
-- [ ] Search your component source files for `useState`, `useEffect`, `useContext`, `useSelector`, `useDispatch`, `useTransition`, `useDeferredValue`, `useNavigate`, `useLocation`, `useParams`, `ReactOnRails.getStore`
+- [ ] Search your component source files for `useState`, `useEffect`, `useContext`, `useRef`, `useReducer`, `useCallback`, `useMemo`, `useTransition`, `useDeferredValue`, `useId`, `useOptimistic`, `useFormStatus`, `useSelector`, `useDispatch`, `useNavigate`, `useLocation`, `useParams`, `ReactOnRails.getStore`, `ReactOnRails.authenticityToken`
 - [ ] Check all `.server.jsx` files -- these almost certainly need `'use client'`
 - [ ] Check components that use `StaticRouter` (SSR wrapper, not a client API — but the file likely uses other client APIs)
 - [ ] Verify no component relies on browser globals (`window`, `document`) without `'use client'`
