Add RSC Flight payload optimization guide (Article 7)#2827
Conversation
Adds a new article to the RSC migration guide series covering when presentational Server Components hurt performance due to Flight payload bloat, and when moving them to Client Components is the better choice. Cross-references added to: - migrating-to-rsc.md: Article 7 in series listing - rsc-component-patterns.md: caveat on Decision Guide table - rsc-troubleshooting.md: expanded RSC Payload Duplication section Closes #2528 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
Note Reviews pausedIt 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 Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughAdded a new documentation article on RSC Flight payload optimization and updated migration guides to warn that repeated, className‑heavy Server Components can bloat Flight payloads; includes measurement methods, examples, tradeoffs (compression vs LCP), and a React on Rails JSON.stringify note. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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 |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
Greptile SummaryThis PR adds Article 7 ("Flight Payload Optimization") to the RSC migration guide series and cross-references it from Articles 2 and 6. The new article documents the counterintuitive pattern where converting high-expansion-ratio presentational components from Server to Client Components can dramatically reduce RSC Flight payload size — backed by real benchmark data (42% payload reduction, 31:1 savings ratio) with an honest discussion of the LCP tradeoff. Key changes:
Issues found:
Confidence Score: 4/5
Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[Presentational component] --> B{Interactive?\nhooks / events / browser APIs}
B -- Yes --> C[Client Component\nstandard RSC rule]
B -- No --> D{Repeated many times\non the page?}
D -- No --> E[Server Component\nstandard RSC rule]
D -- Yes --> F{Element tree much larger\nthan data props?\nroughly 5:1 or higher}
F -- No --> G[Server Component]
F -- Yes --> H{Heavy className\ndensity? e.g. Tailwind}
H -- No --> I[Server Component]
H -- Yes --> J[Consider Client Component\nthis optimization]
J --> K[Measure Flight payload\nbefore and after]
K --> L{Payload reduction\nfavorable?}
L -- Yes, payload -20%+\nJS increase small --> M[✅ Apply optimization\nuse client directive]
L -- No or LCP\ncritical --> N[Keep as Server Component]
Reviews (1): Last reviewed commit: "Add RSC Flight payload optimization guid..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
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-flight-payload.md`:
- Around line 161-163: The current check using script.textContent.includes('$')
is too broad and inflates rscPayloadSize; tighten detection in the block that
increments rscPayloadSize by only counting scripts that match React Server
Components/Flight signatures (e.g., look for specific Flight markers or a more
precise regex rather than a lone '$'). Update the condition around
script.textContent (the script.textContent.includes('$') check) to require a
stricter pattern (for example a regex that matches known Flight token formats or
additional surrounding identifiers) before creating the Blob and adding to
rscPayloadSize so non-Flight scripts are excluded.
🪄 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: 89f2a36c-f447-4214-88dd-d05eb2b6015f
📒 Files selected for processing (4)
docs/oss/migrating/migrating-to-rsc.mddocs/oss/migrating/rsc-component-patterns.mddocs/oss/migrating/rsc-flight-payload.mddocs/oss/migrating/rsc-troubleshooting.md
Review: Article 7 — Flight Payload OptimizationGood addition to the series. The core concept is technically sound and the benchmark data makes the tradeoff concrete. A few issues to fix before merging: Issues requiring attention1. Benchmark numbers presented as "typical" (line 17–23) 2. Brittle payload extraction heuristic (line 161) 3. Non-runnable pseudo-code snippet (lines 172–179) 4. Imprecise LCP explanation (line 198) 5. Missing Minor
|
Review: RSC Flight Payload Optimization (Article 7)This is a well-structured and genuinely useful guide covering a counterintuitive RSC optimization. The content is accurate, the benchmark data is specific (and the math checks out: 67,023 B / 2,152 B ≈ 31:1), and the LCP tradeoff discussion is appropriately balanced. The cross-references in Articles 2 and 6 are correct and the navigation chain is properly wired. A few issues worth addressing before merge: Benchmark caveat needed (TTFB row)The TTFB improvement (-70%, 808ms → 245ms) will surprise readers and may set unrealistic expectations. TTFB reflects server-side serialization time + network RTT — a 67 KB payload reduction alone doesn't typically produce 563ms of savings. The improvement likely comes from React spending less time in the Flight serializer before flushing the first byte, but this varies widely by infrastructure and whether streaming SSR is enabled. A one-sentence note would help. Payload detection heuristic is fragileThe browser console snippet uses a regex heuristic to identify RSC payload in Double JSON.stringify section needs specifics"Depending on your setup" is too vague for readers to know if they're affected. Calling out which render helper or configuration triggers the double-serialization would let readers self-diagnose before opening the linked issue. Decision flowchart missing cumulative bundle guardThe flowchart jumps straight from "high expansion ratio" to "Consider Client Component" without checking whether the cumulative bundle growth is acceptable. Applying this pattern to 20+ components across a large app could grow the bundle meaningfully even if each individual component is small. Minor
All the internal markdown links resolve correctly. The related articles section correctly points to existing files ( |
Review: Add RSC Flight payload optimization guide (Article 7)This is a well-structured and technically sound addition to the RSC migration series. The core insight -- that high expansion-ratio presentational components can produce more payload overhead as Server Components than as Client Components -- is real and often overlooked. The decision flowchart and benchmark table make it actionable. A few issues worth addressing before merge: LCP regression explanation needs clarification (see inline on rsc-flight-payload.md line 206): The article implies moved components are invisible until JS runs. But React on Rails uses SSR -- Client Components still server-render to HTML. The LCP regression mechanism is hydration timing, not content absence before JS. use-client placement examples lack imports (see inline on rsc-flight-payload.md line 102): The guidance that the directive must appear before imports is correct per the React spec, but neither code example includes imports, making the placement rule feel disconnected from real usage. Benchmark environment not characterized: The TTFB numbers (808ms to 245ms, -70%) are dramatic and will shape reader expectations. The caveat note is good, but briefly describing the benchmark environment (dev server vs production, single run vs averaged) would prevent these from being cargo-culted. Programmatic heuristic React on Rails gap: The console snippets are described as approximations (correctly), but there is no React on Rails-specific note on where to locate Flight output. React on Rails may emit it differently than Next.js; readers could run the snippets and see zero results even with RSC enabled. Minor: The double JSON.stringify section links to issue 2522 without indicating it is still open. A note like "(currently open)" keeps the section self-contained as the issue evolves. Overall this is a valuable article -- the pattern is real, the tradeoffs are clearly laid out, and the cross-references integrate it well into the existing series. |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
Review: Add RSC Flight payload optimization guide (Article 7)This is a well-structured and technically solid article on a genuinely counterintuitive performance consideration. The decision flowchart, before/after code examples, and benchmark caveats are good. A few items worth addressing before merge: Missing: JS bundle download cost for all users The optimization discussion correctly notes the +2.2 KB client JS increase, but does not explain who pays that cost. When you add 'use client' to a presentational component, that component's code is added to the JS bundle downloaded by every user on every page load — not just the page where the component appears. The Flight payload savings only apply to specific pages that render those components. A component imported by a shared bundle adds JS cost to all users while payload savings are narrow. The decision criteria should account for bundle scope. The 5:1 threshold may discourage valid optimizations The 'roughly 5:1 or higher' heuristic is presented without much justification. A component with a 3:1 ratio rendered 60 times produces the same aggregate savings as a 6:1 component rendered 30 times. Framing the threshold in terms of total payload impact (ratio x repetition count) would avoid developers dismissing worthwhile optimizations. TTFB/FCP improvements need more prominent scoping The -70% TTFB and -64% FCP numbers are striking but the caveat at line 94 is easy to miss after a data-heavy table. TTFB improvements of that magnitude typically reflect reduced server serialization time under specific benchmark conditions. Consider adding a brief inline note to the table so readers do not take these as representative production gains. Double JSON.stringify scope is unclear The React on Rails double-serialization note links to issue #2522 but does not clarify whether this affects all React on Rails RSC setups or only specific inline-script embedding configurations. A sentence scoping when this overhead occurs would help readers judge whether it applies to them. |
|
This is a well-structured and technically sound documentation addition. The core concept -- that Flight payload expansion ratio matters and some presentational components are better off as Client Components -- is real and underserved in the wider RSC literature. A few issues worth addressing: 1. Unidiomatic clsx usage in code examples -- Both Before/After ProductTags examples use clsx with a single static string, which is identical to a plain className string. The clsx wrapper adds noise and may confuse readers into thinking there is missing conditional logic. See inline comments on the PR for details. 2. Heuristic regex fragility -- The browser console snippets detect Flight data via regex pattern matching, which can produce false positives from analytics scripts or JSON blobs, and may not match the React on Rails payload format. The caveat on line 181 is good, but consider demoting to a labeled quick-prototype approach or leading with a more reliable method. 3. Navigation breadcrumb completeness -- Article 7 has only a Previous navigation link while Articles 1-6 have bidirectional navigation. A small note marking this as the final article in the series would be clear. 4. Issue reference staleness -- Line 232 asserts issue 2522 is currently open with no workaround. This assertion will become stale when resolved. Prefer: "see issue 2522 for current status." Strengths: benchmark numbers are cited with appropriate single-environment caveats; the LCP tradeoff is honestly presented; the decision flowchart accurately models the tradeoff space; the double JSON.stringify React on Rails note is valuable and not covered elsewhere; cross-references in Articles 2 and 6 are well-placed. |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
Review: Add RSC Flight payload optimization guide (Article 7)Overall this is a well-written, technically solid guide. The core insight is correct and counterintuitive enough to be genuinely valuable. The benchmarks are appropriately hedged, the decision flowchart is useful, and the cross-references are well-placed. A few issues worth addressing before merge: Client reference payload size (around line 58 of rsc-flight-payload.md): The guide states a Client Component payload is 'roughly 30 bytes' (equal to the props). This understates the actual size. A client reference entry in the Flight payload includes the module path/ID, chunk IDs, and export name - typically 80-200+ bytes depending on path length - plus the serialized props. The savings claim still holds (far smaller than the expanded element tree), but 'roughly 30 bytes' will confuse readers who inspect their actual payloads and see something larger. Payload analysis script (.join issue): The composition analysis snippet joins matching scripts with newline characters, adding bytes not present in the real payload. This inflates totalBytes and makes the className share fractionally smaller than actual. Negligible for diagnostic use but conflicts with the guide's emphasis on measurement precision. Missing import chain warning in Step 2: The How to Apply section instructs readers to add 'use client' but does not warn about the import chain. A component being converted may import from a module that uses server-only, Rails session helpers, or other server-only utilities, causing a build error. One sentence noting 'ensure neither the component nor its imports use server-only modules' would prevent a common stumbling block. Minor: The benchmark table shows both FCP and LCP at 982 ms before the optimization. This coincidence is worth a brief acknowledgment (e.g., 'FCP and LCP coincide because the LCP element was also the first contentful paint') to preempt reader skepticism. |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
Review: Article 7 RSC Flight Payload Optimization. Well-structured addition to the RSC migration series. The counterintuitive framing is exactly the nuance that trips up RSC adopters. The LCP tradeoff section and benchmark caveats are responsible additions. Four inline comments posted with issues to address: (1) TTFB -70% needs mechanism explanation, (2) missing import-cascade warning at use client step, (3) RSC script detection regex brittleness, (4) double JSON.stringify section could be more actionable. No concerns on technical accuracy of expansion-ratio concept, flowchart, internal links, or code examples. |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
Review: Article 7 - Flight Payload OptimizationThis is a genuinely useful addition to the series. The core concept (expansion ratio x repetition count as the real cost signal) is technically sound and often missing from standard RSC guidance. The benchmark data is specific and the caveats are appropriately honest. Several previously-flagged issues (overly broad dollar-sign heuristic, benchmark not scoped to environment) appear to have been addressed in the current revision. A few remaining items worth addressing before merge: 1. LCP mechanism is slightly incorrect (line 215-218) The article says the converted components require their JS bundle to be parsed and executed before hydration completes -- implying the LCP element is absent from HTML until JS runs. But with SSR, Client Components still render to static HTML. The actual LCP regression comes from React's hydration process potentially causing the browser to re-evaluate paint timing for elements inside hydrated subtrees. If the LCP element sits inside a component that triggers a hydration-driven repaint, the browser may record LCP later -- not because the element was invisible, but because React touched it during reconciliation. The current wording could mislead readers into thinking users see a blank area until JS loads. 2. Decision flowchart missing cumulative bundle guard The flowchart checks per-component JS bundle increase but not cumulative cost when this pattern is applied across many components. A component in a widely-shared client chunk adds JS cost to every page load sitewide, while Flight payload savings only apply to specific pages that render it. Adding a node like "Is the module in a page-specific (not shared) bundle?" before the final recommendation would prevent a common misapplication. 3. Double JSON.stringify terminology React's Flight format is a custom streaming wire protocol, not standard JSON. The second step is Rails JSON-encoding that wire format when embedding it in a script tag -- not two passes of JSON.stringify on the same data. "Double-encoding" or "JSON-encoding of the Flight wire format" would be more accurate and avoids a wrong mental model about what the Flight serializer produces. 4. TTFB figure lacks inline caveat in benchmark table The table shows -70% TTFB. The caveat paragraph that follows is good, but readers who scan tables may cargo-cult this number. Adding a parenthetical note like (buffered SSR) alongside the percentage directly in the table row would help readers who scan rather than read sequentially. 5. Minor: use client placement wording Line 106 says the directive must appear "at the top of the file, before any import statements." React's actual constraint is that it precede any non-directive statements -- file header comments above it are allowed. "At the top of the file" is slightly over-restrictive for developers who use license or copyright headers. Overall close to merge-ready. Items 1 and 2 are worth fixing; 3-5 are minor improvements to precision. |
…olve-2833 * origin/main: docs: fix profiling node renderer command (#2863) generators: point Pro install fallback to upgrade guide (#2868) Add RSC Flight payload optimization guide (Article 7) (#2827) Migrate from deprecated Async::Variable to Async::Promise (#2832) docs: turn pro quick start into a gateway (#2862) Fix upload-assets endpoint duplicating bundles across directories (#2768) docs: fix stale docs links and help URLs (#2850) docs: replace dead pro.reactonrails.com links (#2851) docs: refresh generator and helper URLs (#2852) Add standalone RSC upgrade guide for existing Pro apps (#2831) Raise docs version floor to 16.4.0 in install/demo guidance (#2610) # Conflicts: # CHANGELOG.md
…olve-2834 * origin/main: docs: fix profiling node renderer command (#2863) generators: point Pro install fallback to upgrade guide (#2868) Add RSC Flight payload optimization guide (Article 7) (#2827) Migrate from deprecated Async::Variable to Async::Promise (#2832) docs: turn pro quick start into a gateway (#2862) Fix upload-assets endpoint duplicating bundles across directories (#2768) docs: fix stale docs links and help URLs (#2850) docs: replace dead pro.reactonrails.com links (#2851) docs: refresh generator and helper URLs (#2852) # Conflicts: # CHANGELOG.md # react_on_rails/lib/react_on_rails/utils.rb
…olve-2849 * origin/main: docs: fix profiling node renderer command (#2863) generators: point Pro install fallback to upgrade guide (#2868) Add RSC Flight payload optimization guide (Article 7) (#2827) Migrate from deprecated Async::Variable to Async::Promise (#2832) docs: turn pro quick start into a gateway (#2862) Fix upload-assets endpoint duplicating bundles across directories (#2768) docs: fix stale docs links and help URLs (#2850) docs: replace dead pro.reactonrails.com links (#2851) docs: refresh generator and helper URLs (#2852) Add standalone RSC upgrade guide for existing Pro apps (#2831) Raise docs version floor to 16.4.0 in install/demo guidance (#2610) # Conflicts: # CHANGELOG.md
…olve-2835 * origin/main: (21 commits) docs: fix profiling node renderer command (#2863) generators: point Pro install fallback to upgrade guide (#2868) Add RSC Flight payload optimization guide (Article 7) (#2827) Migrate from deprecated Async::Variable to Async::Promise (#2832) docs: turn pro quick start into a gateway (#2862) Fix upload-assets endpoint duplicating bundles across directories (#2768) docs: fix stale docs links and help URLs (#2850) docs: replace dead pro.reactonrails.com links (#2851) docs: refresh generator and helper URLs (#2852) Add standalone RSC upgrade guide for existing Pro apps (#2831) Raise docs version floor to 16.4.0 in install/demo guidance (#2610) Fix release script: require changelog, fix RC version computation (#2848) Bump version to 16.5.0 Bump version to 16.5.0.rc.0 Update CHANGELOG.md for 16.5.0.rc.0 (#2847) Docs: add memory leak prevention guide for Node Renderer SSR (#2845) Docs: fix RSC migration gaps found during real-world migration (#2842) Add common mistakes sections to RSC migration guides (#2826) fix: preserve runtime env vars across Bundler.with_unbundled_env (#2836) Skip Pro CI workflows for Dependabot PRs (#2825) ... # Conflicts: # CHANGELOG.md
## Summary - Stamped `### [16.5.1] - 2026-03-27` with two Pro fixes (PRs #2872, #2768) - Removed the `### [16.5.0.rc.0]` section (was already released as 16.5.0 stable) - Consolidated the 16.5.0 section with full entries (previously just said "no changes from rc.0") - Updated diff links at bottom of file ## Skipped PRs (docs/internal only) #2856, #2860, #2857, #2859, #2864, #2870, #2863, #2868, #2827, #2862, #2850, #2851, #2852, #2831, #2610, #2848 ## Test plan - [ ] Verify CHANGELOG.md formatting and diff links are correct - [ ] Run `rake release` (no args) after merge to publish 16.5.1 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Low risk: changes are limited to `CHANGELOG.md` release notes and version/compare links with no runtime code modifications. > > **Overview** > Documents the `16.5.1` release by adding a new section under *Unreleased* with two **[Pro]** fixes (missing packaged rake tasks and avoiding duplicated bundles during remote renderer asset uploads). > > Cleans up the `16.5.0` entry by removing the `16.5.0.rc.0` section and updating the compare-link footer so `unreleased` now starts from `v16.5.1` and `16.5.0` compares from `v16.4.0`. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 9a6b224. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY --> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Updated changelog to document version 16.5.1 release with consolidated version history and updated comparison links. <!-- end of auto-generated comment: release notes by coderabbit.ai --> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary - Stamped `### [16.5.1] - 2026-03-27` with two Pro fixes (PRs #2872, #2768) - Removed the `### [16.5.0.rc.0]` section (was already released as 16.5.0 stable) - Consolidated the 16.5.0 section with full entries (previously just said "no changes from rc.0") - Updated diff links at bottom of file ## Skipped PRs (docs/internal only) #2856, #2860, #2857, #2859, #2864, #2870, #2863, #2868, #2827, #2862, #2850, #2851, #2852, #2831, #2610, #2848 ## Test plan - [ ] Verify CHANGELOG.md formatting and diff links are correct - [ ] Run `rake release` (no args) after merge to publish 16.5.1 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Low risk: changes are limited to `CHANGELOG.md` release notes and version/compare links with no runtime code modifications. > > **Overview** > Documents the `16.5.1` release by adding a new section under *Unreleased* with two **[Pro]** fixes (missing packaged rake tasks and avoiding duplicated bundles during remote renderer asset uploads). > > Cleans up the `16.5.0` entry by removing the `16.5.0.rc.0` section and updating the compare-link footer so `unreleased` now starts from `v16.5.1` and `16.5.0` compares from `v16.4.0`. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 9a6b224. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY --> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Updated changelog to document version 16.5.1 release with consolidated version history and updated comparison links. <!-- end of auto-generated comment: release notes by coderabbit.ai --> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 participant
Summary
migrating-to-rsc.md: Article 7 in the series listingrsc-component-patterns.md: footnote caveat on the Decision Guide tablersc-troubleshooting.md: expanded RSC Payload Duplication section with link to new article, and Next link in navigationCloses #2528
Test plan
🤖 Generated with Claude Code
Note
Low Risk
Low risk documentation-only changes; main risk is broken internal links or confusing guidance around server vs client component tradeoffs.
Overview
Adds a new Part 7 RSC migration article,
rsc-flight-payload.md, documenting how to reduce RSC Flight payload bloat (including measurement snippets, decision flowchart, benchmarks, and LCP/TTFB tradeoffs).Updates the migration series index (
migrating-to-rsc.md), refines the server-vs-client decision table inrsc-component-patterns.mdwith a payload-size caveat, and expandsrsc-troubleshooting.mdto reference the new optimization guidance and add next/previous navigation.Written by Cursor Bugbot for commit 5e5f309. This will update automatically on new commits. Configure here.
Summary by CodeRabbit