Walkthrough

Adds a new Pro-focused runbook "Upgrading an Existing Pro App to RSC", links it from the Pro RSC index and OSS migration page, and documents prerequisites, generator usage (rails g react_on_rails:rsc), legacy vs current webpack export compatibility, verification steps, and troubleshooting.

Changes

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• Add RSC upgrade guide for existing Pro apps #2830 — Adds the same dedicated "Upgrading an Existing Pro App to RSC" documentation and index link updates; closely related to this doc addition.

Poem

🐰 I hopped through docs with tidy cheer,
A generator path now crystal clear,
Legacy and current both held tight,
Build and watch till the page feels right,
Tiny paws applaud the upgrade near.

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 adds a new dedicated guide (upgrading-existing-pro-app.md) for adding RSC to an existing React on Rails Pro application via the standalone rails g react_on_rails:rsc generator, and wires in two cross-references from the RSC index and OSS migration hub.

The documentation is thorough: it covers prerequisites, generator usage, legacy vs. current webpack export-shape compatibility, a step-by-step verification checklist, and a troubleshooting section. The webpack compatibility details and the "What the Generator Modifies" table are accurate against rsc_setup.rb.

However, the "What the Generator Creates" table contains incorrect component file paths. The generator (rsc_setup.rb lines 194–218) places the example components under app/javascript/src/HelloServer/{ror_components,components}/, not client/app/components/. The table also omits the third file (ror_components/HelloServer.jsx) that the generator creates as the React on Rails registration entry-point. A user following the guide who tries to locate or inspect these generated files will look in the wrong directory.

• Cross-references (index.md → new page, migrating-to-rsc.md → new page) are accurate and the relative paths resolve correctly.
• All internal anchor links (#step-4-set-up-the-rsc-webpack-bundle, #stream-backpressure-deadlock, etc.) point to real sections that exist in the target files.

Confidence Score: 4/5

• Safe to merge after correcting the generated component file paths in the "What the Generator Creates" table.
• The PR is documentation-only with solid structure and accurate cross-references. There is one concrete factual error — wrong file paths (and a missing file) in the "What the Generator Creates" table — that would directly mislead users following the runbook. Fixing that single table brings the guide to merge-ready quality.
• docs/pro/react-server-components/upgrading-existing-pro-app.md — "What the Generator Creates" table (lines 42–48) has incorrect paths that don't match the actual generator output in rsc_setup.rb.

Important Files Changed

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Start: Existing Pro App] --> B{Prerequisites met?\nRoR Pro 4+, React 19.0.x,\nNodeRenderer, Node 20+}
    B -- No --> C[Fix prerequisites\ne.g. upgrade React, install Pro gem]
    C --> B
    B -- Yes --> D[rails generate react_on_rails:rsc]
    D --> E[Generator creates files\nrscWebpackConfig.js\nHelloServer components\nController + View]
    D --> F[Generator modifies configs\nserverWebpackConfig.js\nclientWebpackConfig.js\nServerClientOrBoth.js\nProcfile.dev + routes.rb]
    E & F --> G[Step 2: Legacy webpack compat\nauto-handled by rscWebpackConfig.js]
    G --> H[Step 3: Verify setup]
    H --> H1[Build check\nbin/shakapacker x3 bundles]
    H --> H2[Manifest files check\nreact-client-manifest.json]
    H --> H3[Route check\ngrep rsc_payload in routes]
    H --> H4[Page render check\nvisit slash hello_server]
    H --> H5[Procfile check\n5 processes + RSC watcher]
    H1 & H2 & H3 & H4 & H5 --> I{All checks pass?}
    I -- No --> J[Troubleshooting\nMissing Pro gem / React mismatch\nManifest missing / Deadlock]
    J --> H
    I -- Yes --> K[Infrastructure ready!\nProceed to React-side migration]

_{Reviews (1): Last reviewed commit: "Add RSC upgrade guide for existing Pro a..." | Re-trigger Greptile}

Good addition - overall structure is solid. Two issues need fixing before merge. (1) Wrong file paths in the 'What the Generator Creates' table - verified against rsc_setup.rb lines 193-218, files actually go under app/javascript/src/HelloServer/ not client/app/components/, and the ror_components/HelloServer.jsx entry-point file is missing from the table entirely - see inline suggestion. (2) CVE-2026-23864 has a 2026 year prefix which is unusual for an existing library, please verify all three CVE IDs are real before merging or replace with release note links. Nit: install commands on lines 25 and 203 are pnpm-only, other docs show all three package managers.

Review: Add RSC upgrade guide for existing Pro apps

Good addition to the docs — the guide is well-structured, covers the right scope (infrastructure only, with cross-refs to component migration guides), and the webpack export compatibility section is particularly useful for legacy apps. Two issues worth fixing before merge:

1. CVE IDs may be incorrect (also affects rsc_setup.rb)

The CVE identifiers in line 27 of the new doc (CVE-2025-55182, CVE-2025-67779, CVE-2026-23864) are copied from react_on_rails/lib/generators/react_on_rails/rsc_setup.rb:90, but they don't match what's recorded in docs/oss/upgrading/release-notes/16.2.0.md, which lists CVE-2025-55183, CVE-2025-55184, and CVE-2025-67779. The one-digit divergence (55182 vs 55183/55184) and the 2026-dated CVE are flags that these may have been hallucinated. Please verify against the official React GitHub Security Advisories and fix in both this guide and the generator.

2. pnpm list depth

Without --depth=0, pnpm list react enumerates every transitive dependency matching that name, which can be noisy. All three check commands in the prerequisites table should use --depth=0 (see inline comment).

Minor / non-blocking

• The guide hardcodes pnpm throughout. If the project supports yarn or npm workspaces, a brief note ("replace pnpm with your package manager") would help those users.
• The idempotency claim in Step 1 is accurate for routes/Procfile/webpack (all guarded by string-inclusion checks in rsc_setup.rb), but created files (HelloServer component, controller, view) are always overwritten on re-run. Worth noting that re-running the generator will reset customized HelloServer example files.

Review: RSC Upgrade Guide

Review: RSC Upgrade Guide

Documentation quality is solid overall — structure is clear, the What the Generator Creates/Modifies tables are accurate against rsc_setup.rb, and all internal cross-references resolve to real sections/anchors. The webpack compatibility section is a genuinely useful addition.

Must-Fix

Unverifiable CVE IDs (line 27)

The note references CVE-2025-55182, CVE-2025-67779, and CVE-2026-23864. CVE sequence numbers in the 55,000–67,000+ range for 2025 are implausibly high — MITRE assigned roughly 40,000 CVEs for all of 2024. These identifiers are very likely hallucinated and will return no results when users try to look them up, which undermines trust in the documentation. Before merging, either:

• Replace with verified CVE IDs (with a link to the NVD/GHSA entry), or
• Replace the parenthetical with a link to the React 19.0.4 release notes / changelog, or
• Drop the CVE parenthetical entirely — the upgrade recommendation stands without it.

Should-Fix

pnpm-only install commands (lines 24–25 and 203–204, prerequisites table)

This was already flagged by CodeRabbit on the first commit but was not addressed in the follow-up commit. Other docs under docs/ show npm/yarn/pnpm side-by-side. See inline comments.

Verified correct

• File paths in the What the Generator Creates table match rsc_setup.rb lines 194–218 exactly (earlier bot comments about wrong paths were based on a prior commit and are now stale)
• All cross-references to rsc-preparing-app.md, rsc-troubleshooting.md, rsc-component-patterns.md, and rsc-data-fetching.md resolve to real sections
• Webpack compatibility prose accurately reflects the backward-compat logic in the generator templates