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

[justin808]

Summary

Fixes #2523

• Replace await getProduct() / await getUser() / await getStats() etc. with Rails controller props and getReactOnRailsAsyncProp across all RSC migration docs
• Rewrite waterfall avoidance section to show Ruby-side emit.call parallelization (threads) instead of JS-side Promise.all / preload patterns
• Replace React Query prefetch+hydrate pattern with initialData from Rails props
• Replace SWR server fetch with Rails props as fallbackData
• Remove all Server Actions ('use server') examples and add explicit unsupported notes throughout
• Reduce React.cache() section — note that getReactOnRailsAsyncProp already returns a cached promise
• Rewrite progressive streaming section to use async props with ERB examples
• Fix migration checklist to reference Rails props and getReactOnRailsAsyncProp
• Add corresponding ERB view examples alongside component code examples

Affected files:

• rsc-data-fetching.md — major rewrite (waterfall, React Query, SWR, use() hook, React.cache(), Server Actions, hybrid pattern, streaming, checklist)
• rsc-component-patterns.md — Patterns 1, 4, 5 + Mistake 4 note
• rsc-context-and-state.md — Providers and Redux examples
• rsc-third-party-libs.md — Form libraries table + Server Action form pattern
• rsc-troubleshooting.md — serialization table, Server Action fix, testing, validation, error catalog

Test plan

• Review each code example for correctness — ERB syntax, async props API, TypeScript types
• Verify all internal links still resolve (anchors may have changed)
• Confirm no remaining await getProduct() / await getUser() patterns outside of the React.cache() and troubleshooting diagnostic sections
• Confirm all 'use server' references are now in warning/unsupported contexts only

🤖 Generated with Claude Code

---

Note

Low Risk
Low risk documentation-only update, but it changes recommended migration patterns (async props, mutations, and caching) so inaccuracies could mislead adopters.

Overview
Updates the RSC migration docs to replace Next.js-style server fetching (async components calling getX()/Promise.all) with React on Rails patterns: Rails-provided sync props plus streamed async props via stream_react_component_with_async_props and getReactOnRailsAsyncProp (with new ERB examples throughout).

Reworks guidance for common integrations: React Query now seeds the client cache via Rails props (initialData), SWR uses Rails props (fallbackData), and the waterfall section is rewritten around Ruby-side emit.call sequencing/parallelization. Removes Server Actions examples and adds explicit notes that 'use server' is unsupported in React on Rails, with updated mutation, CSRF, testing, and validation examples centered on Rails controller endpoints.

^{Written by Cursor Bugbot for commit 9279c97. This will update automatically on new commits. Configure here.}

Summary by CodeRabbit

• Documentation
  • Migration guides now favor props-first: Rails supplies synchronous props and can stream async props into React.
  • New/renamed patterns: Async Props with Suspense, async-prop streaming, and Async Props → client via use().
  • Updated data-fetching, React Query/SWR guidance, and progressive streaming strategies/examples.
  • Replaced Server Actions guidance with Rails-controller form/mutation patterns; added CSRF, testing, and validation notes.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

Replaces Next.js-style Server Component data fetching and Server Actions in migration docs with React on Rails patterns: Rails supplies synchronous props via stream_react_component and async props via stream_react_component_with_async_props / getReactOnRailsAsyncProp; mutations use Rails controller endpoints with CSRF.

Changes

Cohort / File(s)	Summary
Component Patterns & Async Props docs/oss/migrating/rsc-component-patterns.md	Pattern 1 updated to consume Rails-provided product prop; Pattern 4 renamed to “Async Props with Suspense” using getReactOnRailsAsyncProp; Pattern 5 added demonstrating async props to client components via use(); removed Server Actions references.
Context, State & Props Flow docs/oss/migrating/rsc-context-and-state.md	Added ERB stream_react_component examples; ProductPage examples now accept product prop instead of calling await fetches (applies to plain and Redux examples).
Data Fetching Architecture docs/oss/migrating/rsc-data-fetching.md	Rewrote server-side await examples to use Rails sync props and async-prop streaming; changed React Query/SWR patterns to use Rails-provided initialData/fallbackData; reduced React.cache() emphasis; replaced Server Actions with Rails controller POST examples and CSRF usage; updated waterfall/parallelization guidance to show Ruby-side threading + async props.
Third-Party Libraries & Forms docs/oss/migrating/rsc-third-party-libs.md	Removed Server Action form pattern and React 19 Server Actions references; added client-side form examples that POST to Rails endpoints with X-CSRF-Token; explicit note that React on Rails does not support 'use server'.
Troubleshooting & Testing docs/oss/migrating/rsc-troubleshooting.md	Updated serialization boundary table and troubleshooting fixes to remove Server Action examples; replaced Server Action testing/runtime-validation guidance with Rails controller/request-spec testing and model/strong-params validation; recommend controller endpoints for mutations.

Sequence Diagram(s)

sequenceDiagram
  participant Rails as Rails (ERB)
  participant RSC as React Server Component
  participant Child as Child Component
  participant Client as Browser Client

  Rails->>RSC: stream_react_component(props: { title, product })
  Rails->>RSC: stream_react_component_with_async_props(async: { stats, orders })
  RSC->>RSC: getReactOnRailsAsyncProp("stats") → statsPromise
  RSC->>Child: pass statsPromise / ordersPromise as props
  Child->>Child: await statsPromise (server) or use(statsPromise) (client)
  Child->>Client: render incrementally as promises resolve
  Client->>Rails: POST /api/... with X-CSRF-Token (form/mutation)
  Rails->>Client: respond (controller handles mutation)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

"I nibble docs by lamplight, neat and fleet,
Props arrive like clover at my feet,
Rails streams, promises hum and meet,
Forms post safe with CSRF's heartbeat,
A happy rabbit hops — docs complete!" 🐇✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the primary change: replacing Next.js data fetching patterns with React on Rails async props across RSC documentation files.
Linked Issues check	✅ Passed	All coding requirements from issue #2523 are addressed: replaced direct await calls with Rails props/async props, removed Server Actions examples, updated React Query/SWR patterns, rewrote waterfall guidance with Ruby-side parallelization, and updated migration checklist.
Out of Scope Changes check	✅ Passed	All changes are within scope of issue #2523; no unrelated modifications to non-documentation files or unrelated patterns were introduced.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch jg/2523-rsc-docs-data-fetching

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[claude]

Overall this is a solid, well-scoped rewrite. Replacing generic Next.js-style async/await fetch patterns with getReactOnRailsAsyncProp / stream_react_component_with_async_props throughout makes the docs much more accurate for React on Rails users. The consistent addition of ERB view examples alongside JSX is a big usability win, and the removal/replacement of Server Actions content with clear 'not supported' notices prevents a lot of confusion.

A few issues to address before merging:

Bug: missing export default on Stats component — In rsc-component-patterns.md (Pattern 4), the refactored Stats.jsx snippet drops the export default that was there before. A module-only unexported component silently does nothing — readers who copy this will get a blank Suspense slot with no error.

Thread safety: ActiveRecord connections in Ruby threads — The parallel-threads example (Solution 1 in rsc-data-fetching.md) spawns bare Thread.new blocks that call ActiveRecord (User.find, DashboardStats.compute, Post.recent). Rails' connection pool does not automatically check out connections for new threads, so these queries can raise ActiveRecord::ConnectionTimeoutError under load. The example should wrap each block with ActiveRecord::Base.connection_pool.with_connection { ... } or note the requirement. There is also no error handling around threads.each(&:join) — an exception in one thread will be silently swallowed until join re-raises it, by which point other threads may have already emitted partial data.

Misleading BEST label on Solution 2 — Solution 2 (Progressive Streaming) is labeled BEST but its timings (~200ms, ~500ms, ~750ms) show sequential/cumulative execution — it is not faster than Solution 1 (threads). It has different trade-offs (progressive browser delivery vs. parallel queries). Calling one unconditionally best without qualification misleads readers.

Fetch examples lack error handling — Multiple new form/mutation examples (CommentForm, UserForm, ClientForm) call await fetch(...) without checking response.ok or catching errors. Docs examples get copy-pasted into real applications; a minimal check would prevent silent failures.

Product.all.as_json without pagination — Two ERB snippets use Product.all.as_json as a prop. In any real application this loads an unbounded table into memory and serializes it into the page. Either scope/paginate the query in the example, or add a comment clarifying it is simplified for illustration purposes.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/oss/migrating/rsc-component-patterns.md`:
- Around line 167-177: Update the comment in the AddToCartButton example to
remove the “Server Action” wording and instead reference a Rails controller/API
endpoint for performing the mutation; locate the AddToCartButton snippet (and
the nearby mutation example referenced around ProductPage) and replace phrases
like “Server Action or API call for mutation” with “Rails controller or API
endpoint for the mutation” (also apply the same wording change to the other
duplicated snippet mentioned).

In `@docs/oss/migrating/rsc-troubleshooting.md`:
- Around line 80-81: Update the serialization table entry that currently states
functions are allowed "except Server Actions" so it no longer makes an exception
for Server Actions—remove the phrase "except Server Actions" and make the table
entry state functions are allowed (or disallowed) consistent with the guide's
explicit statement that "'use server' / Server Actions are not supported by
React on Rails"; also search the document for other instances of the same
phrasing (the serialization table and the earlier paragraph that mentions
functions) and replace any "except Server Actions" language so the guide
consistently states Server Actions are unsupported and that Rails controller
endpoints must be used for mutations.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 56a3eeb6-3d49-4a22-9bc2-df7c8f28390a

📥 Commits

Reviewing files that changed from the base of the PR and between 5e61260 and 50f6512.

📒 Files selected for processing (5)

• docs/oss/migrating/rsc-component-patterns.md
• docs/oss/migrating/rsc-context-and-state.md
• docs/oss/migrating/rsc-data-fetching.md
• docs/oss/migrating/rsc-third-party-libs.md
• docs/oss/migrating/rsc-troubleshooting.md

[chatgpt-codex-connector]

💡 Codex Review

react_on_rails/docs/oss/migrating/rsc-troubleshooting.md

Line 15 in 50f6512

| Strings, numbers, booleans, `null`, `undefined` | Functions (except Server Actions) |

Remove the unsupported Server Actions exception from the table

This troubleshooting table still tells readers that Server Actions are the one kind of function that can cross the boundary, but the rest of the page now says React on Rails does not support Server Actions at all. Leaving the exception here sends people debugging serialization errors toward an unsupported API instead of the actual fix: function props are always disallowed in this stack.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[greptile-apps]

Greptile Summary

This PR significantly rewrites five RSC migration guide files to replace Next.js-idiomatic data fetching patterns (await getProduct(), Server Actions, Promise.all preload) with React on Rails-native patterns: Rails controller props, getReactOnRailsAsyncProp, and stream_react_component_with_async_props. The overall direction is correct and improves accuracy for React on Rails users.

Key changes:

• rsc-data-fetching.md — rewrites waterfall section to use Ruby threads and sequential emit.call, replaces React Query prefetch/hydrate with initialData, replaces SWR server fetch with fallbackData, removes Server Actions and adds unsupported notes, reduces React.cache() section
• rsc-component-patterns.md — Patterns 1, 4, 5 updated with ERB examples; unsupported Server Actions note added to Mistake 4
• rsc-context-and-state.md — Provider and Redux examples updated with Rails props
• rsc-third-party-libs.md — Form table and Server Action form pattern replaced with Rails controller fetch
• rsc-troubleshooting.md — serialization table, testing, validation sections updated

Issues found:

• rsc-component-patterns.md (Pattern 4): async function Stats is missing export default — a regression from the original that would break any developer copying the file-split example
• rsc-data-fetching.md (waterfall section): Solution 2 (sequential emit.call) is labeled <%# BEST %> and "recommended", but its timing comments show 750ms total — the same as the "BAD" example. Solution 1 (parallel Ruby threads, 300ms) is faster but labeled only "GOOD"
• rsc-data-fetching.md (threads example): Thread.new blocks running ActiveRecord queries have no connection_pool.with_connection wrapper — a connection-pool exhaustion risk worth noting
• rsc-troubleshooting.md (test example): fireEvent.click on an async submit handler without waitFor will produce act() warnings when setContent('') fires in the microtask after the test assertion
• rsc-data-fetching.md (hybrid pattern): React component destructures snake_case props (channel_id, initial_messages) then re-maps to camelCase for children — unusual for React and a potential source of confusion

Confidence Score: 4/5

• Safe to merge after addressing the missing export default on Stats and clarifying the "BEST" / "GOOD" waterfall labels — all other findings are non-blocking P2 suggestions.
• The overall direction and content of the rewrite is accurate and well-structured. The only P1 issue is the missing export default on the Stats component in Pattern 4 — a one-line fix. The remaining issues (performance label inversion, Thread.new connection-pool note, test act() warning, snake_case props) are P2 suggestions that don't break any documented flow. No production code is changed.
• rsc-component-patterns.md (missing export default on Stats) and rsc-data-fetching.md (waterfall section label ordering, Thread.new guidance)

Important Files Changed

Filename	Overview
docs/oss/migrating/rsc-data-fetching.md	Major rewrite replacing Next.js-centric patterns with Rails async props throughout — waterfall section, React Query, SWR, use() hook, React.cache(), Server Actions, and streaming. Two issues: Solution 2 is labeled "BEST" but is sequential (same total latency as "BAD"); bare Thread.new blocks need connection-pool guidance. Snake_case prop names in the hybrid-pattern example are also inconsistent with React conventions.
docs/oss/migrating/rsc-component-patterns.md	Patterns 1, 4, and 5 updated to use Rails props and async props with ERB examples. Pattern 4's Stats child component is missing export default — a regression from the original — that would break any developer copying the file-split example.
docs/oss/migrating/rsc-troubleshooting.md	Server Action references removed and replaced with Rails controller patterns throughout. The new Testing Mutations example uses fireEvent without awaiting the async handler, which can produce act() warnings for readers who copy it verbatim.
docs/oss/migrating/rsc-third-party-libs.md	Form libraries table and Server Action form pattern replaced with Rails controller fetch examples. Changes are clean — React 19 useActionState row replaced with standard forms row, and the form submission example correctly includes X-CSRF-Token.
docs/oss/migrating/rsc-context-and-state.md	ERB view examples added alongside component code for Providers and Redux patterns; async data fetching removed from component bodies and replaced with Rails props. Changes are accurate and consistent.

Sequence Diagram

sequenceDiagram
    participant Browser
    participant Rails as Rails Controller/View
    participant RoR as React on Rails (Node)
    participant SC as Server Component

    Browser->>Rails: GET /page
    Rails->>Rails: Fetch sync props (name, price)
    Rails->>RoR: stream_react_component_with_async_props(sync_props)
    RoR->>SC: Render shell with sync props
    SC-->>Browser: Stream: initial HTML shell

    par Async props stream in independently
        Rails->>Rails: emit.call("reviews", ...)
        Rails->>RoR: async prop: reviews
        RoR->>SC: reviewsPromise resolves
        SC-->>Browser: Stream: reviews content
    and
        Rails->>Rails: emit.call("related", ...)
        Rails->>RoR: async prop: related
        RoR->>SC: relatedPromise resolves
        SC-->>Browser: Stream: related content
    end

    Note over Browser,SC: Suspense boundaries show skeletons until each prop arrives

Loading

_{Last reviewed commit: "Replace Next.js data..."}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/oss/migrating/rsc-data-fetching.md (1)

82-89: ⚠️ Potential issue | 🟠 Major

Update documentation to use correct helper names: stream_react_component and rsc_payload_react_component.

The docs reference stream_react_component_with_async_props and rsc_payload_react_component_with_async_props, but these helpers do not exist in the codebase. The actual helper names are stream_react_component (line 126 in react_on_rails_pro/app/helpers/react_on_rails_pro_helper.rb) and rsc_payload_react_component (line 188). Update all documentation examples to use the correct names.

This affects lines 82, 91, 148, 184, 358, 378, 408, 475, 522, 819, 911, 922 in docs/oss/migrating/rsc-data-fetching.md, plus references in docs/oss/migrating/rsc-third-party-libs.md, docs/oss/migrating/rsc-component-patterns.md, and docs/oss/migrating/rsc-context-and-state.md.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/oss/migrating/rsc-data-fetching.md` around lines 82 - 89, Documentation
examples use non-existent helpers stream_react_component_with_async_props and
rsc_payload_react_component_with_async_props; update every example to use the
actual helper names stream_react_component and rsc_payload_react_component
respectively, ensuring argument/emit usage remains the same (e.g., replace
stream_react_component_with_async_props("ProductPage", props: {...}) do ... end
with stream_react_component("ProductPage", props: {...}) do ... end and
similarly for rsc_payload_react_component), and verify other occurrences in the
migrating docs are updated to match these exact helper symbols.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@docs/oss/migrating/rsc-data-fetching.md`:
- Around line 82-89: Documentation examples use non-existent helpers
stream_react_component_with_async_props and
rsc_payload_react_component_with_async_props; update every example to use the
actual helper names stream_react_component and rsc_payload_react_component
respectively, ensuring argument/emit usage remains the same (e.g., replace
stream_react_component_with_async_props("ProductPage", props: {...}) do ... end
with stream_react_component("ProductPage", props: {...}) do ... end and
similarly for rsc_payload_react_component), and verify other occurrences in the
migrating docs are updated to match these exact helper symbols.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 402c2fb9-3a90-4494-8c81-5d463e61f86e

📥 Commits

Reviewing files that changed from the base of the PR and between 50f6512 and 8902722.

📒 Files selected for processing (3)

• docs/oss/migrating/rsc-component-patterns.md
• docs/oss/migrating/rsc-data-fetching.md
• docs/oss/migrating/rsc-troubleshooting.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/oss/migrating/rsc-troubleshooting.md

[chatgpt-codex-connector]

💡 Codex Review

react_on_rails/docs/oss/migrating/rsc-data-fetching.md

Lines 82 to 83 in 8902722

	<%= stream_react_component_with_async_props("ProductPage",
	props: { name: product.name, price: product.price }) do |emit|

Stop recommending async-props APIs the gem doesn't ship

I ran rg -n "stream_react_component_with_async_props|getReactOnRailsAsyncProp|WithAsyncProps" across the repo, and the only matches are the new migration docs. The shipped Ruby helper is still stream_react_component (react_on_rails_pro/app/helpers/react_on_rails_pro_helper.rb#stream_react_component), and packages/react-on-rails-pro/package.json exports no matching JS/TS API. Readers following this section will hit undefined method stream_react_component_with_async_props or missing-export/type errors before they can apply the documented migration pattern.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Review

This is a solid, well-scoped documentation rewrite. Replacing generic RSC patterns (direct await getProduct(), Server Actions, React.cache() boilerplate) with React on Rails-specific idioms (Rails props, getReactOnRailsAsyncProp, ERB examples) makes the migration guides dramatically more actionable. The Server Actions unsupported notices are well-placed and the Ruby thread parallelism section is a good addition.

A few issues worth fixing before merge:

Bugs / Correctness

1. Flaky test in rsc-troubleshooting.md — The UserForm test calls fireEvent.click (sync) on an async handler and immediately asserts on fetch. This is a race condition; the assertion runs before the promise resolves. Needs waitFor. (Inline comment on line 500–507.)

2. Misleading waterfall comment — posts = user.posts.recent # 250ms (waits for stats too) is inaccurate: posts depends on user, not on stats. The sequential wait is purely because the calls are in order, not a data dependency. (Inline comment on line 366.)

3. Silent fetch failures — CommentForm (rsc-data-fetching.md) and UserForm (rsc-third-party-libs.md, rsc-troubleshooting.md) call await fetch(...) without checking response.ok and still reset state on a failed request. Even for doc examples this models a silent-failure pattern readers will copy. (Inline comment on lines 728–739.)

Missing Context

4. csrfToken prop origin is never shown — All three form examples accept csrfToken as a prop, but none of the ERB snippets in this PR show how to pass it. Readers need to know to use form_authenticity_token. A single line in each ERB block would close the loop. (Inline comment on line 725.)

5. Thread safety of emit — The parallel-thread solution calls emit.call from multiple concurrent threads. If emit writes to a shared HTTP response buffer it needs to be thread-safe. Worth a note confirming this is safe, or restructuring the example to compute in parallel but emit serially. (Inline comment on lines 382–397.)

Minor

6. Product.all.as_json — Used twice in rsc-data-fetching.md without pagination. Fine as a stub but should carry a comment warning against use in production, or use @products (already scoped in the controller). (Inline comment on line 235.)

[claude]

PR Review

This is a valuable, well-scoped documentation rewrite. The direction is right and the ERB examples alongside JSX are a real improvement.

One blocking issue and a few consistency fixes needed before merge.

MUST FIX

1. stream_react_component_with_async_props, getReactOnRailsAsyncProp, and WithAsyncProps do not exist in the codebase.

A repo-wide search confirms these symbols appear only in the new docs - not in react_on_rails_pro/app/helpers/react_on_rails_pro_helper.rb, not in packages/react-on-rails-pro/, and not anywhere else in the Ruby or TypeScript source. The shipped helpers are stream_react_component (line 126) and rsc_payload_react_component (line 188).

Every reader who follows the new Async Props pattern will hit:

• undefined method 'stream_react_component_with_async_props' in ERB
• Unresolved TypeScript import for WithAsyncProps from react-on-rails-pro
• A getReactOnRailsAsyncProp prop that is never injected at runtime

This affects ~15 call sites across all five changed files. If these are planned APIs (docs written ahead of implementation), the examples should either use the currently-shipped API or be clearly labelled as upcoming.

2. Checklist inconsistency (rsc-data-fetching.md line 924)

The migration checklist still says "add server prefetch" for React Query/SWR cases, but the body of the guide now recommends passing Rails props as initialData/fallbackData. These give contradictory guidance to a reader who scans the checklist first.

3. TanStack Query table (rsc-third-party-libs.md line 246)

The Data Fetching Libraries table still describes the old pattern: "Prefetch on server with queryClient.prefetchQuery(), hydrate on client with HydrationBoundary". The rest of this PR switches to the initialData pattern. The table row should match.

DISCUSS

4. prerender: true in RSC context (rsc-context-and-state.md line 317)

The auth provider example uses prerender: true with stream_react_component, which activates the Node SSR path, not the RSC streaming path. May be intentional but is confusing in an RSC migration guide. Worth a clarifying note or removing the flag.

5. Thread error handling (rsc-data-fetching.md lines 388-408)

The parallel threads example has no exception handling. If a thread raises (e.g. ActiveRecord::RecordNotFound), the exception is silently swallowed until threads.each(&:join) re-raises it. By that point no data has been emitted for that key, leaving the Suspense boundary hanging indefinitely. A rescue inside each block or a warning note would make the example production-safe.

[claude]

stream_react_component_with_async_props and getReactOnRailsAsyncProp do not exist in the codebase. A repo-wide search finds these symbols only in the new docs — the shipped Ruby helper is stream_react_component (react_on_rails_pro/app/helpers/react_on_rails_pro_helper.rb:126).

Readers following step 5 will hit undefined method 'stream_react_component_with_async_props' in ERB.

Also, the checklist item just above this block (line 924: "add server prefetch") is inconsistent with the rest of the guide, which now recommends initialData/fallbackData from Rails props. It should be updated to match.

[claude]

Overall this is a solid, well-structured documentation update. The inline comments I posted flag the specific items below.

Bugs (should fix before merge):

• rsc-troubleshooting.md Performance Pitfalls: user_id referenced but never defined in both the sequential BAD example and the threads Fix 1 example — will cause a NameError
• rsc-troubleshooting.md line with posts computation: comment says 'waits for stats' but posts only depends on user, not stats

Clarity (nice-to-have):

• rsc-data-fetching.md Solution 2: UserProfile, StatsPanel, PostFeed are defined without export in the same code block as Dashboard — worth a note that the block is condensed for brevity
• All form examples (CommentForm, UserForm, ClientForm) throw on failure but never update UI state — readers copying these will get silent failures in production

[chatgpt-codex-connector]

💡 Codex Review

react_on_rails/docs/oss/migrating/rsc-data-fetching.md

Lines 82 to 83 in d157b42

	<%= stream_react_component_with_async_props("ProductPage",
	props: { name: product.name, price: product.price }) do |emit|

Replace bare product/post locals in the new ERB snippets

These new examples switched to bare product/post locals, but the snippets never assign those locals first. In a normal Rails view, copying this literally raises undefined local variable or method 'product' before any async props can stream. The same problem recurs in the later mixed-strategy and use() examples in this commit, so the docs should either define the local explicitly or use instance vars (@product, @post) consistently.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Mark the “no JavaScript required” form_with example as local

react_on_rails still supports Rails >= 5.2 (react_on_rails/react_on_rails.gemspec:33), and the Rails guides note that form_with generated remote/Ajax forms by default until the 6.1 defaults flipped that setting (guides.rubyonrails.org/v6.1.0/form_helpers.html, guides.rubyonrails.org/configuring.html#config-action-view-form-with-generates-remote-forms). As written, this “no JavaScript required” snippet still depends on JS on supported 5.2/6.0 apps unless you add local: true or explicitly scope the advice to Rails 6.1+.

Useful? React with 👍 / 👎.

[claude]

Security consideration: Passing form_authenticity_token as a component prop embeds it in the RSC payload (visible in <script> tags in the page source) and in any logging/tracing of component props. The token is session-bound, so exposure isn't catastrophic, but it's better practice to read it from a <meta> tag or a cookie on the client side, which is how Rails' own UJS/Turbo handle it.

An alternative pattern worth mentioning:

<%# In the layout — already present in most Rails apps via csrf_meta_tags %>
<%= csrf_meta_tags %>

<%# Then in the component view, no need to pass the token as a prop %>
<%= stream_react_component("CommentForm",
      props: { postId: @post.id }) %>

// Client Component reads the token directly from the DOM
const csrfToken = document.querySelector('meta[name="csrf-token"]')?.content;

This avoids embedding the token in the serialized props payload and keeps it out of component prop logs.

[claude]

Review: RSC Docs — Replace Next.js patterns with React on Rails async props

Overall this is a high-quality, well-structured rewrite. The core direction — replacing async/await component fetching with Rails props and getReactOnRailsAsyncProp — is correct and the ERB examples throughout are a significant improvement. A few issues worth fixing before merge:

---

🔴 Thread safety in parallel emit pattern (important)

The Ruby threading examples in both rsc-data-fetching.md and rsc-troubleshooting.md use a plain Hash (results = {}) as a shared data structure written from multiple threads. This is not thread-safe. Even under MRI's GVL, the GVL is released during I/O (the with_connection DB query), so threads can reach their write concurrently. Hash mutation is not atomic at the C level — concurrent writes to different keys can corrupt the internal bucket structure.

Fix: use a Mutex around each write, or use Concurrent::Map from concurrent-ruby (already a Rails dependency). See inline comments for a suggested correction.

---

🔴 Incomplete thread failure semantics

The note "An unhandled exception in any thread will be re-raised by join, skipping the remaining emit.call invocations" is accurate but leaves out an important consequence: any async prop whose emit.call was skipped will never resolve on the client. The browser will remain suspended at those Suspense fallbacks indefinitely. The docs should explicitly tell readers to ensure emit.call is always invoked for every registered async prop key — even on error (e.g., emit a sentinel value and handle it in the component).

---

🟡 CSRF token in component props (security consideration)

All the form examples pass csrfToken: form_authenticity_token as a React component prop. This embeds the token in the RSC payload (serialized into <script> tags in the HTML), making it visible in page source, dev tools, and any prop-level logging/tracing.

A lower-exposure alternative — which is already how Rails' own UJS/Turbo work — is to read it from the <meta name="csrf-token"> tag that csrf_meta_tags adds to the layout:

const csrfToken = document.querySelector('meta[name="csrf-token"]')?.content;

Worth at minimum adding a note that both approaches exist and flagging the props approach exposes the token in the serialized payload.

---

🟡 initialDataUpdatedAt: Date.now() re-evaluated on every render

Date.now() inside a component body runs on every render, not just initialization. React Query reads initialDataUpdatedAt on each render to compute staleness — so this effectively tells the library the data was fetched "right now" on every render cycle, which may suppress background refetches when combined with a staleTime. The inline note addresses this, but it would benefit from a Warning callout rather than a plain note since the behavior is easily misunderstood.

---

🟢 Minor: N+1 risk in as_json examples

product.reviews.as_json and product.recommended_products.as_json (in the async props intro) can silently trigger N+1 queries if the serializer traverses nested associations. Worth adding a brief mention of includes in those code comments (e.g., product.reviews.includes(:author).as_json).

---

Positive notes

• The ERB examples alongside every JSX snippet is a big usability win — this was the most common complaint about the old docs.
• The Server Actions → Rails controllers migration is clearly explained and the CSRF/auth implications are called out.
• The React.cache() section is now correctly scoped to the non-async-props use case.
• The migration checklist (Step 2, steps 4–6) is now accurate and actionable.