RSC migration docs: Replace Next.js data fetching patterns with React on Rails async props

[AbanoubGhadban]

Summary

The RSC migration docs (branch 2459-add-rsc-migration-guide) contain data fetching patterns influenced by Next.js that don't match React on Rails' architecture. In React on Rails, data flows from Rails controllers as props (sync or async), not from await calls inside Server Components. The structural patterns (Suspense boundaries, streaming, waterfall avoidance) are correct — but the mechanism shown needs to change from direct fetching to getReactOnRailsAsyncProp.

Issues

A1. await getProduct() / await getUser() throughout examples

Multiple docs show Server Components calling data-fetching functions directly:

async function ProductPage({ productId }) {
  const product = await getProduct(productId);

Should use Rails props (sync) or getReactOnRailsAsyncProp (async) instead. Every such example should also show the corresponding ERB template with stream_react_component or stream_react_component_with_async_props.

Affected files:

• rsc-component-patterns.md — Pattern 1 "After" (line ~177), Pattern 4 (line ~365), Pattern 5 (line ~388)
• rsc-data-fetching.md — React Query "After" (line ~219), SWR "After" (line ~293), waterfall examples (lines ~329-458), use() hook examples (line ~470), hybrid chat pattern (line ~733)
• rsc-context-and-state.md — Providers example (line ~107), Redux example (line ~225)

A2. Waterfall section uses wrong mechanism

rsc-data-fetching.md lines 322-458 discuss sequential vs parallel await calls inside Server Components. The concept is valid but the mechanism is wrong. Should show:

• Ruby side: sequential vs parallel emit.call (using async gem for concurrency)
• JS side: getReactOnRailsAsyncProp with proper Suspense boundaries

A3. React.cache() section overstated

rsc-data-fetching.md lines 598-673 present React.cache() as the primary deduplication mechanism. In React on Rails, getReactOnRailsAsyncProp already returns a cached promise (same object on repeated calls), making React.cache() largely unnecessary. Section should be reduced and reframed.

A4. Server Actions ('use server') — not supported in React on Rails

Server Actions run on the Node renderer, which is a rendering server without access to Rails models, sessions, cookies, or CSRF protection. React on Rails does not support Server Actions. All mentions should be removed and replaced with an explicit note.

Affected files:

• rsc-data-fetching.md lines 675-709 — entire Server Actions section
• rsc-third-party-libs.md lines 139-177 — Server Action form pattern
• rsc-troubleshooting.md — Server Action fix example (line ~48), Testing Server Actions section (line ~408), Runtime Validation section (line ~449), serialization table (lines ~15-20), error messages catalog (line ~497)
• rsc-component-patterns.md line ~504 — 'use client' vs 'use server' note

A5. React Query Prefetch + Hydrate pattern assumes component-level fetching

rsc-data-fetching.md lines 230-282 show creating a QueryClient in a Server Component with queryClient.prefetchQuery(). Should instead show passing Rails props as initialData to React Query on the client side.

A6. Preload pattern with React.cache() — inapplicable

rsc-data-fetching.md lines 394-434 show a "fire-and-forget" preload pattern. Data comes from Rails as props, so there's nothing to preload in the component. Should be removed or replaced with async props equivalent.

A7. Progressive streaming section implies component-level fetching

rsc-data-fetching.md lines 769-801 shows components independently fetching data. Should show components receiving async props via Suspense boundaries.

A8. Data Fetching Migration Checklist wrong for React on Rails

rsc-data-fetching.md lines 849-867 says "Add direct data fetching with await" and "Remove the API route if it was only used by this component." Should say "Receive data as props from Rails controller" and "Use getReactOnRailsAsyncProp for streaming data."

[justin808]

Verified that all 8 items (A1–A8) from this issue have been fully addressed in the current docs:

• A1 – Direct await getProduct()/await getUser() patterns replaced with async props; only residual appearance is in the React.cache() comparison section, which includes explicit caveats that this is not the React on Rails pattern.
• A2 – Waterfall section now uses emit.call on the Ruby side throughout, no JS-side sequential await patterns remain.
• A3 – React.cache() section reduced to ~33 lines with a clear note that getReactOnRailsAsyncProp already handles deduplication.
• A4 – All Server Actions mentions explicitly flag 'use server' as unsupported in React on Rails, with rationale about Node renderer limitations.
• A5 – React Query pattern now shows Rails props passed as initialData instead of prefetchQuery() in a Server Component.
• A6 – Preload pattern noted as optional since async props handle caching.
• A7 – Progressive streaming examples show emit.call() from Rails, not component-level fetching.
• A8 – Migration checklist says "Receive data as props from Rails" and references getReactOnRailsAsyncProp with stream_react_component_with_async_props.

Nothing remaining to address. ✅