Docs: fill upgrade guide gaps for 16.1.x → 16.4.0 migration#2772
Docs: fill upgrade guide gaps for 16.1.x → 16.4.0 migration#2772
Conversation
Add missing upgrade documentation discovered during a Pro + Node Renderer migration from react_on_rails 16.1.2 / react_on_rails_pro 3.3.1 to 16.4.0. - Add v16.3.0 and v16.4.0 sections to the main upgrade guide - Create release notes for 16.3.0 and 16.4.0 - Document Pro version alignment (3.x/4.x → 16.x) in Pro upgrade guide - Add JWT >= 2.7 dependency prerequisite for Pro users - Add bundlePath → serverBundleCachePath rename to migration steps - Add changed defaults table (ssr_timeout, retry_limit, fallback_exec_js) - Clarify when each Pro npm package is needed - Note that react_on_rails gem is redundant when using react_on_rails_pro - Fix stale version examples in Pro README (~> 4.0 → ~> 16.0) - Fix Pro README compatibility matrix (4.x → 16.x) Fixes #2762 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
WalkthroughAdds release notes and upgrade documentation for React on Rails 16.3.0 and 16.4.0, updates Pro distribution and upgrade guidance (version alignment from Pro 3.x/4.x → 16.x, npm package distinctions, gem sourcing), and documents Pro-specific requirements and configuration renames. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 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 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 PR fills documentation gaps for upgraders migrating from react_on_rails 16.1.x / react_on_rails_pro 3.x to 16.4.0. It adds two new release-note files ( Key observations:
Confidence Score: 4/5
Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A["Upgrader: react_on_rails 16.1.x\nreact_on_rails_pro 3.x"] --> B{Which guide?}
B -->|OSS only| C["upgrading-react-on-rails.md"]
B -->|Pro user| D["docs/pro/updating.md"]
C --> C1["## Upgrading to v16.3.0\n(from v16.2.x)\n→ release-notes/16.3.0.md"]
C --> C2["## Upgrading to v16.4.0\n(from v16.3.x)\n→ release-notes/16.4.0.md"]
D --> D1["Version Alignment section\nPro 3.x/4.x → 16.x"]
D --> D2["Migration Steps\n(packages, .npmrc, imports, license)"]
D --> D3["Upgrading to 16.4.0+\n• JWT ≥ 2.7\n• bundlePath → serverBundleCachePath\n• Changed defaults table\n• RSC template format\n• Gemfile redundancy note"]
D --> D4["Understanding Pro npm packages\n• react-on-rails-pro (always)\n• react-on-rails-pro-node-renderer\n (Node Renderer only)"]
C2 -->|Pro users link| D
Last reviewed commit: "Docs: fill upgrade g..." |
Review: Docs — fill upgrade guide gaps for 16.1.x → 16.4.0 migrationGood documentation PR. I verified the technical claims against the codebase and they all check out:
Two inline comments:
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: dde0d0b205
ℹ️ 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".
- Add Pro users callout to 16.3.0 release notes (matching 16.4.0 pattern) - Fix JWT requirement scope: "16.4.0 and later" instead of "16.x" - Fix version alignment table: include Pro 16.1.x on GitHub Packages, clarify that public distribution started at 16.2.0 - Move "Understanding the Pro npm packages" section up to be general guidance visible to all Pro users, not nested under 16.4.0-specific notes Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Review: Docs — fill upgrade guide gaps for 16.1.x → 16.4.0 migrationGood documentation PR. The release notes for 16.3.0 and 16.4.0 are well-structured, breaking changes are clearly called out, and the Pro version-alignment story is now much easier to follow. I verified the technical claims against the codebase:
Three items worth a second look (inline comments posted):
|
There was a problem hiding this comment.
💡 Codex Review
react_on_rails/docs/pro/updating.md
Lines 132 to 134 in 1837400
react-on-rails when migrating package.json
If a GitHub Packages customer already has a top-level react-on-rails dependency — which Step 4 implicitly assumes by telling them to rewrite import ReactOnRails from 'react-on-rails' — this migration leaves that package in place and only adds react-on-rails-pro. That state is a hard failure: ReactOnRails::VersionChecker#validate_no_duplicate_packages! raises when both packages are installed (react_on_rails/lib/react_on_rails/version_checker.rb:103-120), and the troubleshooting guide says the app will not start (docs/oss/migrating/rsc-troubleshooting.md:729-735). Step 3 needs to tell users to remove the old base package, not just add the Pro one.
ℹ️ 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".
- Fix npmjs.org → npmjs.com (canonical domain) in two places - Clarify JWT wording: 16.4.0 "tightened" the requirement (not "requires"), since jwt was already a dependency before 16.4.0 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
Docs review: well-structured PR filling real upgrade guide gaps. Content is accurate, release note files follow the established format, and the Pro README corrections (version matrix, gem version example) are overdue fixes. See inline comments for two minor issues. |
|
|
||
| `react_on_rails_pro` 16.4.0 tightened the `jwt` gem requirement to `~> 2.7`. If your Gemfile pins `jwt` to an older version (e.g., `2.2.x` for compatibility with OAuth gems), you will need to upgrade it. Check for conflicts with: | ||
|
|
||
| ```bash |
There was a problem hiding this comment.
The unqualified bundle update jwt will let Bundler also update any gems whose version constraints become satisfiable once jwt moves — this can cause unexpected version bumps for users who have other gems (e.g., OAuth libraries) that also depend on jwt.
| ```bash | |
| bundle update jwt --conservative |
--conservative restricts the update to jwt itself and is the safer first step for diagnosing the conflict before deciding whether to let other gems float.
|
|
||
| For complete licensing details, see [LICENSE_SETUP.md](https://github.com/shakacode/react_on_rails/blob/master/react_on_rails_pro/LICENSE_SETUP.md). | ||
|
|
||
| ### Understanding the Pro npm packages |
There was a problem hiding this comment.
This section is an h3 (###), which makes it a subsection of the nearest preceding h2 — ## Breaking Changes and Deprecation Policy. That's a misleading home for general npm package orientation content.
Consider moving it to right after the package rename table in ### What's Changing (before "Breaking Changes"), or promoting it to its own h2 like ## Understanding the Pro npm packages. Either placement would help readers find it before they get into migration steps.
| - **TanStack Router SSR**: New `createTanStackRouterRenderFunction` via `react-on-rails-pro/tanstack-router`. [PR 2516](https://github.com/shakacode/react_on_rails/pull/2516). | ||
| - **CSP nonce for immediate hydration and RSC streaming**: Inline `<script>` tags now include CSP nonce attributes. [PR 2398](https://github.com/shakacode/react_on_rails/pull/2398), [PR 2418](https://github.com/shakacode/react_on_rails/pull/2418). | ||
| - **License verification rake task**: New `react_on_rails_pro:verify_license` task with JSON output for CI/CD. [PR 2385](https://github.com/shakacode/react_on_rails/pull/2385). | ||
| - **RSC payload template format**: Pro now renders RSC payload templates with `formats: [:text]` to prevent Rails view annotations from corrupting NDJSON. If you override `custom_rsc_payload_template`, ensure it resolves to a `.text.erb` template. [PR 2535](https://github.com/shakacode/react_on_rails/pull/2535). |
There was a problem hiding this comment.
The corresponding section in docs/pro/updating.md correctly mentions "text or format-neutral template path" as valid options. This note only mentions .text.erb, which is slightly incomplete — a format-neutral path (e.g., no extension or a non-HTML format) also works and may be what some users already have.
| - **RSC payload template format**: Pro now renders RSC payload templates with `formats: [:text]` to prevent Rails view annotations from corrupting NDJSON. If you override `custom_rsc_payload_template`, ensure it resolves to a `.text.erb` template. [PR 2535](https://github.com/shakacode/react_on_rails/pull/2535). | |
| - **RSC payload template format**: Pro now renders RSC payload templates with `formats: [:text]` to prevent Rails view annotations from corrupting NDJSON. If you override `custom_rsc_payload_template`, ensure it resolves to a `.text.erb` or other format-neutral template. [PR 2535](https://github.com/shakacode/react_on_rails/pull/2535). |
## Summary - Stamp `### [16.5.0.rc.0]` version header with today's date - Add 10 new changelog entries for PRs merged since v16.4.0 - Fix incomplete PR 2818 entry (missing author link) ### New entries added **Added:** - `create-react-on-rails-app --pro` support (PR 2818) - Global prerender env override `REACT_ON_RAILS_PRERENDER_OVERRIDE` (PR 2816) - `react_on_rails:sync_versions` rake task (PR 2797) - Pro/RSC setup checks in `react_on_rails:doctor` (PR 2674) **Changed:** - [Pro] Canonical env var for worker count is now `RENDERER_WORKERS_COUNT` (PR 2611) **Improved:** - Smoother `create-react-on-rails-app` and install generator flows (PR 2650) - Pro upgrade hint after install (PR 2642) **Fixed:** - Preserve runtime env vars across `Bundler.with_unbundled_env` (PR 2836) - Fix doctor prerender check and ExecJS display for Pro/RSC apps (PR 2773) - Fix doctor false positives for custom layouts (PR 2612) ### Skipped PRs (not user-visible) Docs-only: #2845, #2842, #2826, #2830, #2820, #2809, #2803, #2785, #2801, #2791, #2789, #2788, #2772, #2778, #2780, #2784, #2671, #2676, #2662, #2657, #2669 CI/internal tooling: #2825, #2817, #2819, #2812, #2815, #2810, #2808, #2807, #2634, #2798, #2761, #2760, #2658, #2639, #2667, #2656 ## Test plan - [x] Verified version header and diff links are correct - [x] Verified all entries follow changelog formatting conventions - [x] Verified file ends with newline - [ ] After merge, run `rake release` to publish 16.5.0.rc.0 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Documentation-only change updating `CHANGELOG.md` with a new `16.5.0.rc.0` section and compare links; no runtime code is modified. > > **Overview** > Adds a new `16.5.0.rc.0` (2026-03-25) section to `CHANGELOG.md`, consolidating recent PR entries under **Added/Changed/Improved/Fixed** and correcting the previously incomplete `--pro` CLI entry author attribution. > > Updates the bottom compare links so `[unreleased]` now compares from `v16.5.0.rc.0` and adds a link definition for `[16.5.0.rc.0]`. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 481a71c. 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 ## Release Notes - v16.5.0.rc.0 * **New Features** * Added sync_versions task for streamlined version management * Expanded doctor checks for Pro and RSC support * **Improvements** * Enhanced generator workflow and Pro upgrade guidance * Improved environment variable handling and preservation * **Bug Fixes** * Fixed detection issues with doctor tools and ExecJS/prerender functionality <!-- end of auto-generated comment: release notes by coderabbit.ai --> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary Fixes #2762 Addresses the documentation gaps discovered during a Pro + Node Renderer migration from react_on_rails 16.1.2 / react_on_rails_pro 3.3.1 → 16.4.0. ### Changes **Main upgrade guide** (`docs/oss/upgrading/upgrading-react-on-rails.md`): - Added upgrade sections for v16.3.0 and v16.4.0 (issue #1) **Release notes** (new files): - `docs/oss/upgrading/release-notes/16.3.0.md` — covers simplified Shakapacker version handling, Pro license model changes (issue #1) - `docs/oss/upgrading/release-notes/16.4.0.md` — covers generator improvements, dev workflow enhancements, Pro breaking changes (issue #1) **Pro upgrade guide** (`docs/pro/updating.md`): - Added "Version Alignment" section explaining Pro 3.x/4.x → 16.x renumbering (issue #2) - Added JWT `>= 2.7` dependency prerequisite (issue #5) - Added changed defaults table: `ssr_timeout`, `renderer_request_retry_limit`, `renderer_use_fallback_exec_js` (issue #6) - Added `bundlePath` → `serverBundleCachePath` rename to migration steps (issue #7) - Added "Understanding the Pro npm packages" section clarifying when each package is needed (issue #8) - Added note that `gem "react_on_rails"` is redundant when using `react_on_rails_pro` (issue #10) **Pro README** (`react_on_rails_pro/README.md`): - Fixed stale version example `~> 4.0` → `~> 16.0` (issue #9) - Fixed compatibility matrix `4.x` → `16.x` with version alignment note (issue #9) - Removed stale git-based install example ### Items already covered in existing docs Issues #3, #4, #11, #12 were already documented in `docs/pro/updating.md` (package rename table, Gemfile source migration, .npmrc cleanup, import statement migration). No changes needed. ## Test plan - [ ] Verify all internal doc links resolve correctly - [ ] Review release notes for accuracy against CHANGELOG - [ ] Confirm changed defaults table values are accurate for Pro 3.x → 16.x transition 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Low risk: documentation-only changes with no runtime/code impact, though incorrect guidance could mislead upgrades if inaccurate. > > **Overview** > Adds new release notes for `v16.3.0` and `v16.4.0`, documenting upgrade steps plus key generator/dev-workflow/SSR/Pro changes and notable breaking items. > > Expands the main upgrade guide with dedicated `v16.3.0`/`v16.4.0` sections calling out required Pro actions (license env var migration and RSC payload template format change). > > Updates Pro migration docs and README to clarify Pro `3.x/4.x → 16.x` version alignment, package roles, `jwt` requirement, node-renderer config rename (`bundlePath` → `serverBundleCachePath`), redundant `react_on_rails` Gemfile entry, and fixes stale version examples. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit b253fb8. 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** * Added release notes for v16.3.0 and v16.4.0 with upgrade steps and version bump guidance. * Documented Pro vs OSS package/install guidance and migration notes (Pro 16.x successor to Pro 3/4). * Noted Pro license behavior change (evaluation/dev optional; production requires license) and env-var license option. * Simplified Shakapacker requirements and generator/dev workflow improvements. * Described SSR/rendering fixes, node-renderer guidance, CSP nonce support, and other Pro-specific config/default changes. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary Fixes #2762 Addresses the documentation gaps discovered during a Pro + Node Renderer migration from react_on_rails 16.1.2 / react_on_rails_pro 3.3.1 → 16.4.0. ### Changes **Main upgrade guide** (`docs/oss/upgrading/upgrading-react-on-rails.md`): - Added upgrade sections for v16.3.0 and v16.4.0 (issue #1) **Release notes** (new files): - `docs/oss/upgrading/release-notes/16.3.0.md` — covers simplified Shakapacker version handling, Pro license model changes (issue #1) - `docs/oss/upgrading/release-notes/16.4.0.md` — covers generator improvements, dev workflow enhancements, Pro breaking changes (issue #1) **Pro upgrade guide** (`docs/pro/updating.md`): - Added "Version Alignment" section explaining Pro 3.x/4.x → 16.x renumbering (issue #2) - Added JWT `>= 2.7` dependency prerequisite (issue #5) - Added changed defaults table: `ssr_timeout`, `renderer_request_retry_limit`, `renderer_use_fallback_exec_js` (issue #6) - Added `bundlePath` → `serverBundleCachePath` rename to migration steps (issue #7) - Added "Understanding the Pro npm packages" section clarifying when each package is needed (issue #8) - Added note that `gem "react_on_rails"` is redundant when using `react_on_rails_pro` (issue #10) **Pro README** (`react_on_rails_pro/README.md`): - Fixed stale version example `~> 4.0` → `~> 16.0` (issue #9) - Fixed compatibility matrix `4.x` → `16.x` with version alignment note (issue #9) - Removed stale git-based install example ### Items already covered in existing docs Issues #3, #4, #11, #12 were already documented in `docs/pro/updating.md` (package rename table, Gemfile source migration, .npmrc cleanup, import statement migration). No changes needed. ## Test plan - [ ] Verify all internal doc links resolve correctly - [ ] Review release notes for accuracy against CHANGELOG - [ ] Confirm changed defaults table values are accurate for Pro 3.x → 16.x transition 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Low risk: documentation-only changes with no runtime/code impact, though incorrect guidance could mislead upgrades if inaccurate. > > **Overview** > Adds new release notes for `v16.3.0` and `v16.4.0`, documenting upgrade steps plus key generator/dev-workflow/SSR/Pro changes and notable breaking items. > > Expands the main upgrade guide with dedicated `v16.3.0`/`v16.4.0` sections calling out required Pro actions (license env var migration and RSC payload template format change). > > Updates Pro migration docs and README to clarify Pro `3.x/4.x → 16.x` version alignment, package roles, `jwt` requirement, node-renderer config rename (`bundlePath` → `serverBundleCachePath`), redundant `react_on_rails` Gemfile entry, and fixes stale version examples. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit b253fb8. 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** * Added release notes for v16.3.0 and v16.4.0 with upgrade steps and version bump guidance. * Documented Pro vs OSS package/install guidance and migration notes (Pro 16.x successor to Pro 3/4). * Noted Pro license behavior change (evaluation/dev optional; production requires license) and env-var license option. * Simplified Shakapacker requirements and generator/dev workflow improvements. * Described SSR/rendering fixes, node-renderer guidance, CSP nonce support, and other Pro-specific config/default changes. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Summary
Fixes #2762
Addresses the documentation gaps discovered during a Pro + Node Renderer migration from react_on_rails 16.1.2 / react_on_rails_pro 3.3.1 → 16.4.0.
Changes
Main upgrade guide (
docs/oss/upgrading/upgrading-react-on-rails.md):Release notes (new files):
docs/oss/upgrading/release-notes/16.3.0.md— covers simplified Shakapacker version handling, Pro license model changes (issue TODO for first version #1)docs/oss/upgrading/release-notes/16.4.0.md— covers generator improvements, dev workflow enhancements, Pro breaking changes (issue TODO for first version #1)Pro upgrade guide (
docs/pro/updating.md):>= 2.7dependency prerequisite (issue Add Unit tests #5)ssr_timeout,renderer_request_retry_limit,renderer_use_fallback_exec_js(issue Detailed Setup and Usage Docs #6)bundlePath→serverBundleCachePathrename to migration steps (issue Clean up app/startup/clientApp.jsx and app/startup/serverApp.jsx #7)gem "react_on_rails"is redundant when usingreact_on_rails_pro(issue Support generator to build a template wepack setup #10)Pro README (
react_on_rails_pro/README.md):~> 4.0→~> 16.0(issue Support configuration options #9)4.x→16.xwith version alignment note (issue Support configuration options #9)Items already covered in existing docs
Issues #3, #4, #11, #12 were already documented in
docs/pro/updating.md(package rename table, Gemfile source migration, .npmrc cleanup, import statement migration). No changes needed.Test plan
🤖 Generated with Claude Code
Note
Low Risk
Low risk: documentation-only changes with no runtime/code impact, though incorrect guidance could mislead upgrades if inaccurate.
Overview
Adds new release notes for
v16.3.0andv16.4.0, documenting upgrade steps plus key generator/dev-workflow/SSR/Pro changes and notable breaking items.Expands the main upgrade guide with dedicated
v16.3.0/v16.4.0sections calling out required Pro actions (license env var migration and RSC payload template format change).Updates Pro migration docs and README to clarify Pro
3.x/4.x → 16.xversion alignment, package roles,jwtrequirement, node-renderer config rename (bundlePath→serverBundleCachePath), redundantreact_on_railsGemfile entry, and fixes stale version examples.Written by Cursor Bugbot for commit b253fb8. This will update automatically on new commits. Configure here.
Summary by CodeRabbit