Walkthrough

Docs and config updates clarifying React on Rails migration: emphasize Rails controller props and async props, adjust RSC examples (ProductPage, React Query, caching, waterfalls, streaming), add two Lychee URL exclusions, and normalize a docs URL in CONTRIBUTING.md.

Changes

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 I nibble docs where Rails seeds grow,
Props tumble down where fresh data flows,
Async props hum while slow bits bake,
Client code lightens with every break,
Hooray—less bundle, more carrot cake 🥕✨

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.

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

Greptile Summary

This PR re-frames three RSC migration documentation files around React on Rails' Rails-centric data model, replacing generic "async Server Component fetches data directly" examples with the idiomatic pattern of receiving data as Rails controller props (or streaming it via async props). The changes are largely editorial and improve the coherence of the guide for a Rails audience.

Key changes:

• rsc-data-fetching.md: Pattern 1 "After" example now uses ProductList({ products }) instead of async function ProductList() + await getProducts(); Pattern 2 replaced the dehydrate/HydrationBoundary prefetch pattern with an initialData approach seeded from Rails props; contextual "React on Rails note" callouts added to the waterfalls, use(), and React.cache() sections.
• rsc-component-patterns.md: Pattern 1 heading and intro reframed from "move data fetching to server" to "reduce bundle size / eliminate unnecessary JavaScript / enable streaming"; the After example simplified to accept product as a prop.
• rsc-context-and-state.md: Two code examples (multi-provider composition and Redux donut pattern) updated to accept product as a prop rather than calling await getProduct(productId).

Issues found:

• The initialData example in Pattern 2 (React Query) omits initialDataUpdatedAt, which causes React Query to treat the Rails data as immediately stale and fire a background refetch on every component mount. initialDataUpdatedAt: Date.now() (or a non-zero staleTime) should be added or at least noted.
• The "Hybrid Pattern: Server Fetch + Client Updates" example in the "When to Keep Client-Side Fetching" section still uses async function ChatPage + await getMessages(channelId) — the exact pattern the PR now explicitly marks as "not recommended."
• The Migration Checklist numbered list skips item 6 after two steps were removed from Step 2 (now ends at 5), while Step 3 still starts at 7.

Confidence Score: 3/5

• Safe to merge after addressing the initialData stale-time omission and the inconsistent Hybrid Pattern example, which could mislead readers following the guide.
• The doc changes are well-targeted and the Rails-props framing is clearer. However, the initialData example without initialDataUpdatedAt is a factual gap that could cause production apps to make unnecessary API calls, the Hybrid Pattern example directly contradicts the PR's core advisory, and there is a numbered-list continuity error in the checklist. These issues lower confidence slightly below a clean merge.
• docs/oss/migrating/rsc-data-fetching.md — the initialData stale-time behavior, the Hybrid Pattern inconsistency, and the numbered-list skip all live here.

Important Files Changed

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    RC[Rails Controller] -->|"prepares data"| SP[Sync Props\nname, price, user...]
    RC -->|"via stream_react_component_with_async_props"| AP[Async Props\nreviews, recommendations...]

    SP -->|"passed immediately"| SC[Server Component\nno async/await needed]
    AP -->|"streamed via Suspense"| SC

    SC -->|"display-only subtree"| RSC[Child Server Components\nno JS shipped]
    SC -->|"interactive subtree"| CC["Client Components\n'use client'"]

    CC -->|"needs polling / optimistic updates"| RQ["React Query\ninitialData = Rails props\ninitialDataUpdatedAt = Date.now()"]
    CC -->|"needs real-time / WebSocket"| WS[WebSocket / SSE\ninitialMessages from Rails]
    CC -->|"needs Redux / Zustand"| GS[Global State Library\ndata from Rails props as initial values]

    RQ -->|"background refetch"| API["/api endpoint"]
    WS -->|"persistent connection"| WS2[WebSocket server]

_{Last reviewed commit: b79e87b}

Overall this is a well-executed reframing. The core insight -- that Rails controllers already handle data fetching so the RSC migration goal shifts to reducing client bundle size and enabling streaming rather than moving fetching to the server -- is exactly the right framing for a Rails audience. The contextual callout boxes are well-placed and the simplification of Pattern 2 (dropping dehydrate/HydrationBoundary in favour of initialData) reduces cognitive load for the common case. Three issues to address: (1) initialData stale-time -- see inline comment on line 279; (2) Hybrid Pattern ChatPage at line 815 still uses async/await getMessages directly, contradicting the new anti-pattern note; (3) minor: initialData vs placeholderData distinction not documented. Details below in inline comments and thread.

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

Overall this is a solid, focused improvement. The framing changes are accurate and the additions (TanStack Query dehydrate/HydrationBoundary tip, async props callouts, initialData inline comment) will genuinely help readers unfamiliar with the Rails-props-first mental model.

Three things worth addressing:

D4 not reflected in the diff: The description says D4 replaced await getProduct(productId) with Rails props in rsc-context-and-state.md, but that file is not in the diff and that pattern is not present in it today. Either this was done in a prior commit and the description is stale, or it was planned but not implemented. Please clarify or add the missing change.

getReactOnRailsAsyncProp(key) needs a Pro attribution and link: The updated React.cache() note references this function without indicating it lives in the Pro package. OSS-only readers will not find it. It should be marked as "(React on Rails Pro)" with a link to the relevant Pro docs section.

Waterfall section lost useful explanatory prose: The old intro stated "When queries execute one after another, rendering is delayed by their total time," which concretely explains why waterfalls hurt before showing the code examples. The replacement note points to solutions but drops this motivation entirely. Consider preserving that sentence so the section is self-contained.

Good documentation improvements overall. The reframing around Rails props as the primary data delivery mechanism is accurate and helpful, and the async props references tie things together well.

One minor observation: in the Avoiding Server-Side Waterfalls section, the original intro explicitly called out that "rendering is delayed by their total time" — a concrete framing that helps readers understand why sequential queries are costly. The new blockquote note doesn't include that, though the Ruby code example below (with # 750ms total comment) still illustrates it. Worth deciding whether the total-time framing belongs in the prose or if the code comment is sufficient.

Everything else looks solid:

• The Pattern 1 context note clearly distinguishes Rails RSC adoption goals from generic RSC goals.
• The React.cache() note's mention of getReactOnRailsAsyncProp(key) caching behaviour is a useful addition.
• The TanStack Query dehydrate/HydrationBoundary alternative note is a good pointer for complex cases.
• The .lychee.toml exclusion is well-commented.

Overall this is a solid documentation improvement. The React on Rails context callouts make the migration path much clearer, and the props-first framing is more accurate for the RoR workflow than generic RSC advice.

One blocker: getReactOnRailsAsyncProp(key) at line 537 of rsc-data-fetching.md - this function name does not exist anywhere in the codebase (searched OSS and Pro packages). A wrong API name in migration docs is a direct user trap. See the inline comment.

Two minor items: (1) The new TanStack Query link to tanstack.com/query/... is not covered by the existing lychee exclusion (which only targets tanstack.com/router). Worth watching whether the lychee CI job passes. (2) A blank line between StatsPanel and PostFeed in the waterfall examples was removed - cosmetic, but restoring it improves readability.

Everything else looks good: The React on Rails context callout in Pattern 1 correctly reframes the goal as bundle size reduction and streaming rather than moving data fetching. All anchor links to data-fetching-in-react-on-rails-pro are valid. The React Query initialData and SWR fallbackData examples are correct. The dehydrate/HydrationBoundary alternative is a useful addition. The CONTRIBUTING.md trailing-slash fix is correct. The new lychee exclusions are well-targeted.

Review: Reframe RSC migration docs around React on Rails patterns

Overall this is a clean, focused documentation improvement. The reframing around Rails controller props as the primary data source is accurate and will reduce confusion for developers migrating to RSC.

Strengths:

• The "React on Rails context" callout in Pattern 1 accurately corrects a common misconception — Rails already handles server-side data, so the RSC migration goal is bundle reduction and streaming, not "moving data to the server"
• The React.cache() note mentioning getReactOnRailsAsyncProp(key) returning a cached Promise is a valuable technical detail
• The TanStack Query dehydrate/HydrationBoundary alternative note fills a real documentation gap for complex multi-query cases
• URL updates in NEWS.md and CONTRIBUTING.md are appropriate housekeeping

Minor observations:

1. PR description D4 vs actual diff: The description claims D4 "Replaced await getProduct(productId) with Rails props in Pattern 2 and Redux examples in context-and-state guide", but rsc-context-and-state.md is not in the diff. Checking that file, it already uses the Rails props pattern (e.g., ProductPage({ product }) at the Redux Toolkit example). The description appears to reference prior work — worth updating the PR description for accuracy.

2. Blank line removed between StatsPanel and PostFeed (rsc-data-fetching.md line ~388): The diff removes a blank line separating two function component definitions in a code example. For code readability, keeping the blank line between top-level function declarations is conventional JS/React style.

3. Wording in waterfalls section: The new blockquote ("The primary React on Rails solutions are controller props and async props") reads a bit abruptly as the section opening since it precedes "### The Problem" without a transitional sentence. The old prose ("the most critical performance pitfall is sequential data fetching...") served as better context-setting before the problem/solution structure.

None of these block merging. The documentation changes are accurate and valuable.

Review: Reframe RSC migration docs around React on Rails patterns

The framing improvements are solid — correctly positioning the RSC migration goal as "reduce bundle size and enable streaming" rather than "move data fetching to the server" is the right call for a Rails audience. The context callouts are well-placed and the pattern examples read naturally. One blocker needs to be resolved before merging.

Blocker

getReactOnRailsAsyncProp(key) does not exist in the codebase (line 543, rsc-data-fetching.md). Grepping both OSS and Pro packages returns zero matches. Documenting a phantom API in migration docs is a hard user trap — see the inline comment for options.

Should-fix

Missing lychee exclusion for tanstack.com/query (line 265). The existing exclusion covers tanstack.com/router; the new TanStack Query SSR link uses tanstack.com/query and is not excluded. This will likely fail the link-checker CI job if that domain has the same intermittent timeout issues. Add the exclusion to .lychee.toml alongside the existing one.

Minor

• Waterfall section opener (line 310): The replacement blockquote leads with solutions before the reader has seen the problem. The original prose sentence ("when queries execute one after another, rendering is delayed by their total time") was the motivation — consider folding it into the new blockquote rather than dropping it. Inline suggestion provided.

• Blank line between StatsPanel and PostFeed (line 392): The diff removes the blank line separating two top-level function declarations in the code example. Restoring it costs nothing and improves scannability. Inline suggestion provided.

• PR description D4 is stale: The description says D4 "Replaced await getProduct(productId) with Rails props in Pattern 2 and Redux examples in context-and-state guide," but rsc-context-and-state.md is not in the diff and already uses the Rails props pattern. The description appears to reference prior work. Worth updating to avoid reviewer confusion.

Review: Reframe RSC migration docs around React on Rails patterns. Overall solid doc improvement. Issues: (1) rsc-data-fetching.md:545 mentions Pro-only APIs getReactOnRailsAsyncProp and addAsyncPropsCapabilityToComponentProps with no link to docs -- OSS users will be confused. (2) rsc-data-fetching.md:233 comment says 'Rails data renders instantly' but it is the initialData option that eliminates the loading state -- Rails is just the source. (3) Multiple locations use [async props] link text pointing to a Pro section without indicating it is a Pro feature -- [async props (Pro)] would help. (4) Spurious blank-line removal between StatsPanel and PostFeed adds diff noise.

size-limit report 📦

Review: Reframe RSC migration docs around React on Rails patterns

The changes are well-targeted — consistently replacing generic async/await patterns with the Rails props-first framing, and correctly calling out where async props (Pro) fits into the picture.

One bug to fix:

Lines 261–263 in docs/oss/migrating/rsc-data-fetching.md contain an exact duplicate of the > **Alternative:** blockquote (the TanStack Query dehydrate/HydrationBoundary note). The second copy should be removed. I've left an inline suggestion.

Everything else looks good:

• NEWS.md: correctly removes the two duplicated 2016 entries.
• .lychee.toml: the added exclusions are well-commented and scoped tightly (anchored regexes, inline rationale). The GitHub PR link exclusions are appropriate given intermittent 502s from CI.
• react_on_rails_pro/CONTRIBUTING.md: trailing-slash fix on the docs URL is correct.
• The reframed Pattern 1 note (controller prepares data, no async/await in the component, recommendation against bypassing Rails auth/caching) is accurate and adds useful context for developers coming from other RSC frameworks.
• The initialDataUpdatedAt/staleTime clarification and the React.cache() async-props callout are both accurate improvements over the previous text.

Follow-up on skipped feedback triage:\n\n- initialDataUpdatedAt/staleTime gap: skipped because current content already includes both settings and explanatory notes.\n- getReactOnRailsAsyncProp API-name concern: skipped as stale after rebase; the current text no longer names that API directly.\n- Hybrid pattern async/await concern: skipped as stale; the current ChatPage example is props-based.\n- PR description mismatch (D4): skipped because the PR description was already updated to match the current 4-file scope.\n- Remaining blank-line/prose/note-consolidation suggestions: skipped as non-blocking editorial preference items for this PR scope.\n\nIf you want, I can take a separate docs-polish pass for those purely editorial suggestions in a follow-up PR.

Overall this is a good documentation cleanup. The framing around Rails controller props is clearer, the duplicate NEWS.md entries are removed, and the CONTRIBUTING.md URL fix is correct.

Three issues worth addressing:

1. Duplicate notes about initialDataUpdatedAt / staleTime

The PR adds a new brief note before 'How it works' (line 250), then the existing detailed note immediately after (line 259) covers the same ground plus more. Two adjacent notes explaining the same pair of options is redundant. The brief one should be removed, or both should be merged into a single note.

2. 'async props' links to a section that never defines the term

Five new uses of 'async props' link to the 'Data Fetching in React on Rails Pro' section. That section opens with a description of stream_react_component and never uses the phrase 'async props'. A reader following the link will not find a definition. Either introduce 'async props' by name in that section's heading or opening paragraph, or link to a more targeted location (e.g. the Pro RSC tutorial) that explains the concept.

3. Pattern 1 no longer shows the Rails side

The ERB code block showing stream_react_component was removed from Pattern 1. Pattern 1 now shows Before/After React components but gives no example of how the products prop arrives from Rails. Pattern 2 still has its ERB snippet, making Pattern 1 feel incomplete. A one-liner ERB example or a cross-reference to Pattern 2 would fill the gap.

Review Summary

This is a clean, well-targeted docs-only PR. The reframing around Rails controller props / async props makes the migration guide much more coherent for a Rails audience.

Positives

• ERB block reordering (Pattern 1): Moving the ERB snippet before the After JSX component improves reading flow.
• as_json(only: [:id, :name]): Scoping serialized fields avoids accidentally exposing sensitive columns in copy-pasted examples — good security improvement over the bare as_json call.
• Expanded initialDataUpdatedAt / staleTime note: the original was easy to misread as pick one.
• TanStack Query dehydrate/HydrationBoundary callout: good addition for teams with more complex query graphs.

Minor issues (see inline comments)

1. Blank line dropped between functions — the diff incidentally removes the separator between StatsPanel and PostFeed in the waterfall example.
2. The bypasses Rails authorization wording is too absolute — the async Server Component pattern only bypasses Rails auth layers if the developer omits the checks. Worth softening to avoid stating it as a categorical technical fact.

Out of scope

The .lychee.toml and NEWS.md changes are unrelated maintenance items. Harmless, but worth splitting into a separate PR for cleaner history.