Skip to content

Clarify streaming narrative in RSC migration docs: distinguish HTML streaming from progressive data streaming #2813

@justin808

Description

@justin808

Context

PR #2803 replaced fictional async-props APIs with real stream_react_component patterns. During review, multiple reviewers flagged that the docs now conflate two distinct concepts under "streaming":

  1. HTML streamingrenderToPipeableStream streams rendered HTML progressively as React renders the component tree. Works with stream_react_component + synchronous props.
  2. Progressive data streaming — Slow data sources resolve independently and stream results to the browser, filling in Suspense placeholders. Requires async Server Components + Suspense boundaries (as shown in docs/pro/streaming-ssr.md).

Problem

Several sections use titles like "Progressive Streaming Architecture" and "Streaming Slow Data" but show code that loads ALL data synchronously in Rails before anything is sent. The HTML streaming is real, but it's not "progressive" in the way users expect — no data arrives incrementally.

Affected files and sections

  • docs/oss/migrating/rsc-data-fetching.md — "Progressive Streaming Architecture" (line ~679), "How it works" steps (line ~126)
  • docs/oss/migrating/rsc-component-patterns.md — Pattern 4 description (line ~334)
  • docs/oss/migrating/rsc-context-and-state.md — Pattern 3 description (line ~127)

Additional: as_json(include:) without only: scopes

The @product.as_json(include: [:specs, :reviews]) pattern used in 3 files serializes all columns of included associations. While less sensitive than user data, it's inconsistent with the current_user.as_json(only: [...]) pattern the PR introduced. Consider either:

  • Adding only: scopes to included associations
  • Adding a brief comment recommending only: for production use

Suggested approach

  • Accurately describe the synchronous-props pattern (all data loads before rendering starts — simpler but not progressive)
  • For truly progressive streaming, show the async Server Component + Suspense pattern from docs/pro/streaming-ssr.md
  • Align section titles with what the code actually demonstrates

References

Closes: n/a (follow-up from #2803)

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions