Clarify streaming narrative in RSC docs (#2813)

[justin808]

Summary

• Rename misleading section titles ("Progressive Streaming Architecture" → "Streaming HTML Delivery", "Streaming Slow Data" → "Streaming HTML Delivery") to accurately reflect what the code demonstrates
• Update descriptions across 4 docs files to clarify that with synchronous props, all data loads in Rails before rendering begins — the streaming is HTML streaming (renderToPipeableStream), not progressive data streaming where slow data arrives independently
• Add a callout distinguishing HTML streaming from progressive data streaming, with a link to streaming-ssr.md for the latter
• Scope as_json(include:) calls with only: to avoid serializing all columns of included associations, consistent with existing current_user.as_json(only: [...]) patterns

Fixes #2813

Test plan

• Verify all internal doc links resolve correctly
• Review that section titles match what the code examples actually demonstrate
• Confirm the HTML streaming vs progressive data streaming distinction is clear

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation-only updates that reword streaming guidance and adjust example as_json field selection; no runtime code paths are modified.

Overview
Clarifies the RSC migration docs’ streaming narrative to emphasize that stream_react_component streams rendered HTML via React’s renderToPipeableStream after Rails has synchronously loaded props (and not progressive data streaming). This renames related section headings (e.g., to Streaming HTML Delivery) and adds an explicit callout contrasting HTML streaming vs progressive data streaming with a pointer to the Pro streaming SSR guide.

Updates ERB examples across the guides to scope as_json serialization using only: for included associations (e.g., specs, reviews, recommendations) to avoid implying full-column serialization in recommended patterns.

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

Summary by CodeRabbit

• Documentation
  • Clarified that Rails loads all data synchronously and that HTML is streamed to the browser as React renders component trees.
  • Renamed/reframed sections to emphasize "Streaming HTML Delivery" and explicit use of React’s streaming renderer.
  • Updated migration guidance and examples to use more selective prop serialization for nested data.
  • Clarified contrast between HTML streaming and progressive data streaming.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 40643a11-99de-4ed7-91ee-0a52fe9a6819

📥 Commits

Reviewing files that changed from the base of the PR and between 8e07d46 and 0ff60ae.

📒 Files selected for processing (2)

• docs/oss/migrating/rsc-context-and-state.md
• docs/oss/migrating/rsc-data-fetching.md

✅ Files skipped from review due to trivial changes (1)

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

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

• docs/oss/migrating/rsc-context-and-state.md

---

Walkthrough

The PR updates migration docs to clarify that stream_react_component streams rendered HTML via React's renderToPipeableStream after Rails loads props synchronously, distinguishes this from progressive data streaming (async Server Components + Suspense), and narrows example prop serialization for associations using only:.

Changes

Cohort / File(s)	Summary
Prop serialization examples docs/oss/migrating/rsc-component-patterns.md, docs/oss/migrating/rsc-context-and-state.md, docs/oss/migrating/rsc-preparing-app.md	Replaced broad as_json(include: [:specs, :reviews]) with nested include using only: subsets (specs: { only: [...] }, reviews: { only: [...] }) and updated related ERB/controller examples.
Streaming narrative and headings docs/oss/migrating/rsc-component-patterns.md, docs/oss/migrating/rsc-context-and-state.md, docs/oss/migrating/rsc-data-fetching.md	Renamed sections and reworded explanations to state stream_react_component streams HTML as React renders (uses renderToPipeableStream), that Rails loads data synchronously before streaming begins, and to contrast this with progressive data streaming via async Server Components + Suspense.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 I hopped through lines to sort the streams,
HTML trickles while Rails loads dreams.
Props pared down to only what's due,
Streams sing softly as React queues.
A carrot cheer for docs made true! 🥕

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main objective: clarifying the streaming narrative in RSC documentation to distinguish HTML streaming from progressive data streaming.
Linked Issues check	✅ Passed	The PR successfully addresses all coding and documentation requirements from issue #2813: clarified streaming terminology across four docs, distinguished HTML streaming from progressive data streaming, scoped as_json(include:) calls with only: filters, and linked to docs/pro/streaming-ssr.md.
Out of Scope Changes check	✅ Passed	All changes are scoped to documentation updates in four RSC migration files with no unrelated modifications; broader docs reorganization and placeholder-column guidance are explicitly noted as future work.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch jg/2813-rsc-streaming-docs

---

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.}

[greptile-apps]

Greptile Summary

This PR clarifies the streaming narrative across four RSC migration docs, accurately distinguishing HTML streaming (what stream_react_component / renderToPipeableStream actually does when all props are synchronous) from progressive data streaming (where slow data sources resolve independently via Suspense). It also adds a helpful callout in rsc-data-fetching.md that links to docs/pro/streaming-ssr.md for readers who need the latter, and scopes all as_json(include:) calls with only: to avoid serializing every column of included associations.

Key changes:

• Renamed "Progressive Streaming Architecture" → "Streaming HTML Delivery" and "Streaming Slow Data" → "Streaming HTML Delivery" to match what the code examples actually demonstrate.
• Updated prose in all four files to make clear that Rails loads all data synchronously before renderToPipeableStream begins, so the streaming benefit is latency/TTFB of the HTML response, not independent data resolution.
• Added a callout distinguishing HTML streaming from progressive data streaming, with a verified link to streaming-ssr.md.
• Scoped as_json(include: [:specs, :reviews]) to as_json(include: { specs: { only: [...] }, reviews: { only: [...] } }) — an important best-practice improvement to avoid leaking all association columns to the client.
• All renamed section anchors have no inbound references that would break; internal links verified correct.

Confidence Score: 5/5

• Safe to merge — documentation-only PR with accurate technical corrections and a minor but useful security/best-practice improvement to example code.
• All changes are in documentation files. The streaming terminology clarification is technically accurate, all renamed section anchors have no inbound broken references, both new links resolve to existing files, and the as_json scoping change is a strictly-better code example pattern. No regressions possible.
• No files require special attention.

Important Files Changed

Filename	Overview
docs/oss/migrating/rsc-data-fetching.md	Largest set of changes: section renames ("Progressive Streaming Architecture" → "Streaming HTML Delivery"), updated descriptions throughout to distinguish HTML streaming from progressive data streaming, and adds a new callout explaining the distinction with a verified link to docs/pro/streaming-ssr.md.
docs/oss/migrating/rsc-context-and-state.md	Renames "Pattern 3: Streaming Slow Data" to "Pattern 3: Streaming HTML Delivery", updates prose to reflect that all data is loaded synchronously before HTML streaming begins, and scopes the as_json(include:) call with only: to avoid over-serializing association columns.
docs/oss/migrating/rsc-component-patterns.md	Updates Pattern 4 description to clarify that stream_react_component performs HTML streaming rather than progressive data streaming, and scopes the as_json(include:) call with only: constraints.
docs/oss/migrating/rsc-preparing-app.md	Two code examples updated to scope as_json(include:) with only: — one in the before-migration snippet and one in the after-migration snippet — consistent with the changes in the other files.

Sequence Diagram

sequenceDiagram
    participant Browser
    participant Rails
    participant React as React renderToPipeableStream

    Browser->>Rails: HTTP GET /products/123
    note over Rails: Controller loads all data synchronously
    Rails->>React: stream_react_component with all props
    note over React: HTML streaming begins immediately
    React-->>Browser: HTML chunk 1 header and nav
    React-->>Browser: HTML chunk 2 main content
    React-->>Browser: HTML chunk 3 recommendations and comments

Loading

_{Reviews (1): Last reviewed commit: "Clarify streaming narrative in RSC docs:..." | Re-trigger Greptile}

[claude]

Review

The terminology clarification here is accurate and a real improvement. The old 'progressive streaming' / 'streaming slow data' titles were genuinely misleading, and the new callout box distinguishing HTML streaming from progressive data streaming is the standout addition.

Issue 1: Hardcoded example column names in as_json snippets

The new only: scoping is the right pattern, but the specific column names (label, value, text, rating) are fictional placeholders. Without a prose note making that explicit, readers are likely to copy-paste them literally and get silent empty results or nil fields. A code comment or a sentence beneath each block noting 'replace with your actual column names' would prevent this.

Issue 2: The streaming-ssr.md link goes to a Pro feature without flagging it

The new callout in rsc-data-fetching.md ends with a link to streaming-ssr.md for progressive data streaming. Since that page covers a React on Rails Pro capability, non-Pro users following the link may be confused. Worth adding '(React on Rails Pro)' inline.

Issue 3: Subsection title / parent section mismatch

The renamed subsection 'Streaming HTML Delivery' now sits under the 'Loading States and Suspense Boundaries' parent section. The new description emphasises that all data is loaded synchronously before rendering begins, but 'Loading States' implies async states. The subsection content predates this PR so this is not a regression, but the rename makes the mismatch more visible — a bridging sentence or reorganisation may help.

Minor nit

In rsc-data-fetching.md, list item 5 says 'The component renders with zero JavaScript cost as a Server Component' which is only true when the tree contains no Client Components. Worth a qualifier, though this predates the PR.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c59a4adbc9

ℹ️ 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".

[justin808]

Addressed the review feedback:

Issue 2 (Pro link): Fixed in 637bf81 — added "(React on Rails Pro)" to the streaming-ssr.md link so non-Pro readers have clear context.

Issue 1 (placeholder column names): Declining — the column names are intentionally generic example placeholders. Adding "replace with your actual columns" notes to every snippet would clutter the docs.

Issue 3 (subsection/parent mismatch): Acknowledged but out of scope — the placement under "Loading States and Suspense Boundaries" predates this PR. The rename makes it slightly more visible, but restructuring parent sections would expand scope. Better addressed in a dedicated docs reorganization.

Issue 4 (minor nit on "zero JavaScript cost"): Agreed this is pre-existing and not introduced by this PR, so leaving as-is.

[coderabbitai]

Actionable comments posted: 1

🤖 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-data-fetching.md`:
- Around line 132-134: Combine the two adjacent blockquote lines so there's no
blank quoted line between them: remove the empty quoted line separating "**HTML
streaming vs. progressive data streaming:** ..." and "**More details:** ..." so
they form a contiguous blockquote, or alternatively split them into two separate
blockquote blocks without an empty quoted gap; ensure there are no blank lines
that start with ">" between the quoted lines to satisfy markdownlint MD028.

🪄 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: 496624a5-9a3e-4673-899c-d16110c52683

📥 Commits

Reviewing files that changed from the base of the PR and between c59a4ad and 637bf81.

📒 Files selected for processing (1)

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

[claude]

Review

The terminology clarification is accurate and a genuine improvement. The old "progressive streaming" / "streaming slow data" framing was misleading, and the new callout box distinguishing HTML streaming from progressive data streaming is the most valuable addition. The (React on Rails Pro) qualifier on the streaming-ssr.md link (added in 637bf81) is correct.

Inconsistent as_json scoping

The PR description says it scopes as_json(include:) with only: to avoid serializing all association columns. That was done for the Pattern 1 / Pattern 3 examples in rsc-component-patterns.md and rsc-preparing-app.md, but the How Streaming Works code block in rsc-data-fetching.md was not updated — it still shows:

reviews: product.reviews.includes(:author).as_json,
recommendations: product.recommended_products.as_json

The same unscoped pattern appears again in the Solution 3: Pass All Data as Props block further down that file. Both were left without only: scoping, even though the surrounding prose in each section was modified by this PR. Readers following those sections will see unscoped examples directly alongside prose that was just clarified, which undercuts the serialization best-practice message.

If the intent was to fix the complete file rather than just the include: [...] array form, these two blocks should also be scoped. If the intent was narrower, the PR description overstates what was done.

[justin808]

Addressed in 8e07d46 — the two unscoped .as_json calls in the "How Streaming Works" and "Solution 3" code blocks now use only: scoping, consistent with the other examples in the PR. Good catch on the inconsistency.

[claude]

Overall the changes are accurate and well-targeted. Distinguishing HTML streaming from progressive data streaming is a real source of confusion, and this PR addresses it clearly. The as_json(only: ...) scoping additions are a good security/performance practice.

Three issues worth fixing before merge:

1. Inconsistent as_json scoping in rsc-context-and-state.md Pattern 3 -- The PR scopes as_json for associations elsewhere, but the Pattern 3 example still uses bare .as_json without only: for reviews and recommendations. See inline comment.

2. Wasteful includes(:author) after only: filter -- In rsc-data-fetching.md the example uses product.reviews.includes(:author).as_json(only: [:id, :text, :rating]). The includes(:author) eagerly loads the author association but only: [:id, :text, :rating] only serializes review fields, so all author data is loaded and silently discarded. Either drop includes(:author) or add include: { author: { only: [:id, :name] } } to justify the eager load. As written, this teaches readers to write a subtly wasteful query.

3. Markdownlint MD028 (already flagged by CodeRabbit) -- The new callout in rsc-data-fetching.md uses a blank > line to separate two blockquote paragraphs, violating MD028. The two items should either be one continuous blockquote or two separate blockquotes with a non-quoted blank line between them.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8e07d469f3

ℹ️ 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".

[justin808]

Replying to review summary #2814 (review):

The MD028 point was a duplicate of the inline thread and is now addressed in the docs update. No additional action needed beyond that inline fix.

[justin808]

Replying to #2814 (comment):

Thanks for the detailed review. The three blocking items called out there were addressed in this update:

1. Added scoped serialization in rsc-context-and-state.md Pattern 3.
2. Removed unused includes(:author) from the two rsc-data-fetching.md examples where only review fields are serialized.
3. Removed the blank quoted line in the streaming callout block to satisfy MD028.

[justin808]

Replying to #2814 (comment):

Thanks for the thoughtful pass. Current status:

• Pro-link clarity concern is already handled ((React on Rails Pro) was added).
• The placeholder-column note and parent-section organization points are being treated as optional scope-expansion for a future docs pass, not blocking this PR.
• The “zero JavaScript cost” wording note predates this PR and is also tracked as optional follow-up wording cleanup.

[chatgpt-codex-connector]

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

[claude]

Review

The terminology clarification (HTML streaming vs. progressive data streaming) is accurate and the added callout pointing readers to streaming-ssr.md for true progressive streaming is a good addition. The rename of "Progressive Streaming Architecture" → "Streaming HTML Delivery" is also correct.

Two issues worth fixing:

1. Merged blockquotes (rendering bug)
In rsc-data-fetching.md, the new "HTML streaming vs. progressive data streaming" callout and the existing "More details" note are placed on consecutive > lines with no separator. CommonMark renders them as a single merged blockquote, losing the visual distinction. A blank > line between them fixes it. See inline comment.

2. Dropped .includes(:author) (silent N+1 regression in examples)
Three examples previously showed product.reviews.includes(:author).as_json, which modeled the important ActiveRecord eager-loading pattern. The PR replaces this with product.reviews.as_json(only: [...]), removing .includes(:author) entirely. Since author fields are no longer in the only: list it doesn't break anything today, but readers who copy the snippet and later add author fields will hit N+1 queries with no indication they need eager loading. Worth keeping .includes(:author) in the chain even if the serialized fields don't include author columns. See inline comments on rsc-context-and-state.md and rsc-data-fetching.md.

[claude]

Review: Clarify streaming narrative in RSC docs. The terminology clarifications are accurate and the HTML-streaming-vs-progressive-data-streaming callout is a clear improvement. Two issues are worth addressing before merge. (1) Inconsistent only: scoping - The PR correctly scopes several as_json calls but rsc-data-fetching.md lines 693-695 still have main_content.as_json, RecommendationService.for(@page).as_json, @page.comments.recent.as_json without only:. Same for rsc-data-fetching.md:645 and rsc-component-patterns.md:382. The doc itself warns against bare as_json at line 847. (2) includes(:author) dropped without explanation - product.reviews.includes(:author).as_json became product.reviews.as_json(only: [:id, :text, :rating]) which is correct, but rsc-component-patterns.md:382 still has post.comments.includes(:author).as_json without only:. One example drops eager loading silently while another keeps it without field-scoping. The updated examples also no longer illustrate N+1 prevention. (3) Minor: Streaming HTML Delivery section sits under Loading States and Suspense Boundaries heading which implies async rendering, though the content correctly explains synchronous props mean no Suspense boundaries are involved.

[claude]

The updated description is accurate, but the code example that follows (lines 693–695) still uses unscoped as_json:

main_content: @page.main_content.as_json,
recommendations: RecommendationService.for(@page).as_json,
comments: @page.comments.recent.as_json

This contradicts both the only: scoping added elsewhere in this PR and the doc's own warning against bare as_json (~line 847). Consider adding only: with the fields the Page component actually renders to keep the examples consistent.

[claude]

Good — only: scoping added here. Note that rsc-component-patterns.md:382 (Pattern 5) still uses post.comments.includes(:author).as_json without only:, which is now inconsistent with this pattern. That example also no longer demonstrates N+1 prevention since the eager-loaded :author association is never field-scoped. Worth addressing here or in a follow-up for consistency.