docs: clarify how React on Rails compares to alternatives#2856
docs: clarify how React on Rails compares to alternatives#2856
Conversation
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
WalkthroughDocumentation reorganized: README gained a "Choosing the Right Rails + Frontend Stack" section; the comparison guide was restructured into higher-level option comparisons, added "Next.js + Rails API", and updated recommendations and SSR descriptions. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 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 |
Greptile SummaryThis is a documentation-only PR that adds a decision-oriented comparison matrix to Key changes:
All relative links ( Confidence Score: 5/5Safe to merge — documentation-only changes with no code impact, accurate content, and all links verified. Both changed files are Markdown documentation. Content is factually consistent with the rest of the repo (oss-vs-pro.md exists, relative links resolve, feature claims match the codebase). The architectural reframing is clear and well-reasoned. No broken links, no removed content that was load-bearing elsewhere, and no risk of regression. No files require special attention. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[Choosing a Rails + React stack] --> B{Want React at all?}
B -- No --> C[Hotwire / Turbo\nHTML-over-the-wire]
B -- Yes --> D{Keep Rails as main app?}
D -- No --> E[Next.js + Rails API\nFrontend-led architecture]
D -- Yes --> F{Integration style?}
F -- Full-page SPA pages\nwith Rails controllers --> G[Inertia Rails + React\nNo separate JSON API]
F -- React inside Rails views --> H{SSR / RSC needs?}
F -- DIY / maximum flexibility --> I[Vite Ruby + React\nManual mounting]
H -- No SSR, simpler integration --> J[react-rails\nBasic ExecJS SSR]
H -- Built-in SSR\nor upgrade path --> K[React on Rails OSS\nExecJS SSR, view helpers]
H -- Node SSR, streaming,\nRSC, high-traffic --> L[React on Rails Pro\nNode renderer, RSC, streaming]
K -- Need advanced features? --> L
Reviews (1): Last reviewed commit: "docs: clarify how React on Rails compare..." | Re-trigger Greptile |
Review: docs: clarify how React on Rails compares to alternativesOverall this is a solid, well-structured documentation improvement. The shift to an architectural/decision-oriented framing is more useful than a raw feature checkbox table, and adding the Next.js + Rails API section fills a real gap. A few things worth addressing before merging: Issues1. Relative links in README will break on the hosted docs site The new "Recommended default" paragraph uses file-relative links ( 2. Next.js section links to App Router reference, not the homepage
3. Loss of specific feature-level comparison The old table had scannable ✓/— entries for concrete capabilities (code splitting with SSR, SSR caching, hot module replacement, active maintenance status, etc.). The new table is better for architectural decision-making but loses the ability to quickly spot whether a specific feature exists. Consider whether a link to the detailed OSS vs Pro matrix is enough to fill this gap for users who arrive at the comparison page looking for feature-level answers — it may be worth keeping a concise feature grid alongside the new architectural table. Minor observations
|
There was a problem hiding this comment.
🧹 Nitpick comments (2)
README.md (1)
201-201: Optional copy polish at Line 201.“deeper look” could be replaced with “detailed comparison” for slightly crisper phrasing.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` at line 201, Replace the phrase "deeper look" in the README sentence starting with "See [Comparison with Alternatives](https://reactonrails.com/docs/getting-started/comparison-with-alternatives/)" with "detailed comparison" so the line reads using the crisper phrasing "See [Comparison with Alternatives]... for a detailed comparison of Inertia, Vite Ruby, react-rails, Next.js, and Hotwire."docs/oss/getting-started/comparison-with-alternatives.md (1)
195-195: Consider tightening wording at Line 195.“very carefully” is slightly vague; a sharper phrase (e.g., “with explicit boundary design”) reads more concretely.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/oss/getting-started/comparison-with-alternatives.md` at line 195, Replace the vague phrase in the sentence "Duplicates routing, auth/session, and deployment concerns across two layers unless designed very carefully" with a concrete alternative; update that line (the sentence) to read something like "Duplicates routing, auth/session, and deployment concerns across two layers unless there are clearly defined boundaries and ownership" (or use "with explicit boundary design") to make the guidance more specific.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@docs/oss/getting-started/comparison-with-alternatives.md`:
- Line 195: Replace the vague phrase in the sentence "Duplicates routing,
auth/session, and deployment concerns across two layers unless designed very
carefully" with a concrete alternative; update that line (the sentence) to read
something like "Duplicates routing, auth/session, and deployment concerns across
two layers unless there are clearly defined boundaries and ownership" (or use
"with explicit boundary design") to make the guidance more specific.
In `@README.md`:
- Line 201: Replace the phrase "deeper look" in the README sentence starting
with "See [Comparison with
Alternatives](https://reactonrails.com/docs/getting-started/comparison-with-alternatives/)"
with "detailed comparison" so the line reads using the crisper phrasing "See
[Comparison with Alternatives]... for a detailed comparison of Inertia, Vite
Ruby, react-rails, Next.js, and Hotwire."
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 26357f62-f34c-4f5d-827f-c321f6df75bc
📒 Files selected for processing (2)
README.mddocs/oss/getting-started/comparison-with-alternatives.md
Match the dominant link style in the README by using absolute reactonrails.com URLs instead of relative file paths. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
There was a problem hiding this comment.
🧹 Nitpick comments (1)
README.md (1)
201-201: Optional: Consider alternative wording.Static analysis suggests "deeper" might be strengthened with a different adjective (e.g., "detailed", "comprehensive", "thorough"). However, the current wording is perfectly acceptable.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` at line 201, Replace the adjective "deeper" in the sentence beginning "See [Comparison with Alternatives]..." with a stronger alternative such as "detailed", "comprehensive", or "thorough" (e.g., "See [Comparison with Alternatives] for a detailed look...") to improve wording clarity; update the single sentence in README.md where that phrase appears.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@README.md`:
- Line 201: Replace the adjective "deeper" in the sentence beginning "See
[Comparison with Alternatives]..." with a stronger alternative such as
"detailed", "comprehensive", or "thorough" (e.g., "See [Comparison with
Alternatives] for a detailed look...") to improve wording clarity; update the
single sentence in README.md where that phrase appears.
Review: docs: clarify how React on Rails compares to alternativesThe architectural reframing is a genuine improvement. Shifting from a raw feature-checkbox table to a decision-oriented matrix is more useful for developers evaluating stacks. The Next.js + Rails API section fills a real gap. A few issues worth addressing before merging: Issues1. Next.js link drops users into the App Router API reference The Next.js link in the new section points to 2. Hotwire "Built-in SSR path" value is misleading The Hotwire row entry for "Built-in SSR path" reads 3. Loss of specific feature-level comparison The old table had scannable entries for concrete capabilities: code splitting with SSR, SSR caching, HMR, auto-bundling, type-safe routing, and active maintenance status. The new table uses qualitative values ("Excellent", "Good", "DIY") that are more opinion-based. Users with a specific capability question ("does X support SSR caching?") can no longer get a quick answer. Worth considering whether a link to the OSS vs Pro matrix is enough of a bridge, or whether a compact feature grid should be kept alongside the new architectural table. Minor
|
## 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) <[email protected]>
…olve-2835 * origin/main: Bump version to 16.5.1 Update CHANGELOG.md for 16.5.1 (#2873) fix: include lib/tasks/ in pro gem so rake tasks are available (#2872) docs: clarify how React on Rails compares to alternatives (#2856) docs: fix published setup guidance gaps (#2860) docs: refresh setup and runtime guidance (#2857) docs: refresh pro upgrade examples (#2859) docs: modernize dependency update commands (#2864) Update spec/dummy Gemfile.lock for async >= 2.29 (#2870) # Conflicts: # CHANGELOG.md
…olve-2849 * origin/main: Bump version to 16.5.1 Update CHANGELOG.md for 16.5.1 (#2873) fix: include lib/tasks/ in pro gem so rake tasks are available (#2872) docs: clarify how React on Rails compares to alternatives (#2856) docs: fix published setup guidance gaps (#2860) docs: refresh setup and runtime guidance (#2857) docs: refresh pro upgrade examples (#2859) docs: modernize dependency update commands (#2864) Update spec/dummy Gemfile.lock for async >= 2.29 (#2870) # Conflicts: # CHANGELOG.md
…olve-2828 * origin/main: Bump version to 16.5.1 Update CHANGELOG.md for 16.5.1 (#2873) fix: include lib/tasks/ in pro gem so rake tasks are available (#2872) docs: clarify how React on Rails compares to alternatives (#2856) docs: fix published setup guidance gaps (#2860) docs: refresh setup and runtime guidance (#2857) docs: refresh pro upgrade examples (#2859) docs: modernize dependency update commands (#2864) Update spec/dummy Gemfile.lock for async >= 2.29 (#2870) # Conflicts: # CHANGELOG.md
…olve-2834 * origin/main: Bump version to 16.5.1 Update CHANGELOG.md for 16.5.1 (#2873) fix: include lib/tasks/ in pro gem so rake tasks are available (#2872) docs: clarify how React on Rails compares to alternatives (#2856) docs: fix published setup guidance gaps (#2860) docs: refresh setup and runtime guidance (#2857) docs: refresh pro upgrade examples (#2859) docs: modernize dependency update commands (#2864) Update spec/dummy Gemfile.lock for async >= 2.29 (#2870) # Conflicts: # CHANGELOG.md
…olve-2833 * origin/main: Bump version to 16.5.1 Update CHANGELOG.md for 16.5.1 (#2873) fix: include lib/tasks/ in pro gem so rake tasks are available (#2872) docs: clarify how React on Rails compares to alternatives (#2856) docs: fix published setup guidance gaps (#2860) docs: refresh setup and runtime guidance (#2857) docs: refresh pro upgrade examples (#2859) docs: modernize dependency update commands (#2864) Update spec/dummy Gemfile.lock for async >= 2.29 (#2870) # Conflicts: # CHANGELOG.md
…olve-2661 * origin/main: Clarify streaming narrative in RSC docs (#2813) (#2814) Bump version to 16.5.1 Update CHANGELOG.md for 16.5.1 (#2873) fix: include lib/tasks/ in pro gem so rake tasks are available (#2872) docs: clarify how React on Rails compares to alternatives (#2856) docs: fix published setup guidance gaps (#2860) docs: refresh setup and runtime guidance (#2857) docs: refresh pro upgrade examples (#2859) docs: modernize dependency update commands (#2864) Update spec/dummy Gemfile.lock for async >= 2.29 (#2870) # Conflicts: # docs/oss/migrating/rsc-data-fetching.md
Reframe the alternatives comparison from a feature checkbox to a decision-oriented guide that helps readers pick the right stack. - Add "Choosing the Right Rails + Frontend Stack" table to README with 7 options (RoR, RoR Pro, Inertia, Vite Ruby, react-rails, Next.js, Hotwire) - Replace the old feature-presence grid in comparison-with-alternatives.md with columns focused on architectural fit (Keep Rails? Incremental React? SSR path? Operational model? Best when?) - Add Next.js + Rails API section with strengths/trade-offs - Correct Vite Ruby SSR characterization from "no SSR" to "DIY/experimental" - Mention Evil Martians Inertia starter kit as a polished Inertia example - Use absolute reactonrails.com URLs in README for link consistency All alternative tool claims verified against official documentation. Co-Authored-By: Justin Gordon <[email protected]> Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
## 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) <[email protected]>
Summary
Test plan
npx prettier --check README.md docs/oss/getting-started/comparison-with-alternatives.md .claude/napkin.mdbundle exec rubocop(reports pre-existing offenses onmainin unrelated Ruby files; no Ruby files were changed in this PR)pnpm run lint(could not run in this clean worktree becausenode_modulesis not installed here)Note
Low Risk
Low risk: documentation-only changes that add/reshape comparison guidance without affecting runtime code or APIs.
Overview
Adds a new decision-oriented “Rails + frontend stack” comparison matrix to the
README, including guidance on when to choose OSS vs Pro.Reworks
docs/oss/getting-started/comparison-with-alternatives.mdto focus on architectural fit (incremental-in-views vs full-page), SSR/RSC/streaming paths, and operational tradeoffs; adds a dedicated Next.js + Rails API section and clarifies the Evil Martians starter kit as an Inertia example, plus minor wording updates to SSR caveats.Written by Cursor Bugbot for commit 7101f2d. This will update automatically on new commits. Configure here.
Summary by CodeRabbit