Skip to content

Docs: fill upgrade guide gaps for 16.1.x → 16.4.0 migration#2772

Merged
justin808 merged 3 commits intomainfrom
jg/2762-upgrade-guide-gaps
Mar 21, 2026
Merged

Docs: fill upgrade guide gaps for 16.1.x → 16.4.0 migration#2772
justin808 merged 3 commits intomainfrom
jg/2762-upgrade-guide-gaps

Conversation

@justin808
Copy link
Copy Markdown
Member

@justin808 justin808 commented Mar 20, 2026

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):

Pro README (react_on_rails_pro/README.md):

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


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 (bundlePathserverBundleCachePath), redundant react_on_rails Gemfile 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

  • 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.

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>
@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented Mar 20, 2026

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 6efe7cc6-bc5b-4934-be27-f48561bc0f9e

📥 Commits

Reviewing files that changed from the base of the PR and between 1837400 and b253fb8.

📒 Files selected for processing (1)
  • docs/pro/updating.md
✅ Files skipped from review due to trivial changes (1)
  • docs/pro/updating.md

Walkthrough

Adds 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

Cohort / File(s) Summary
Release Notes
docs/oss/upgrading/release-notes/16.3.0.md, docs/oss/upgrading/release-notes/16.4.0.md
New release note pages with upgrade steps, version bumps for gem/npm (OSS and Pro), key changes (Shakapacker requirement simplification, generator and SSR improvements), bug fixes, and Pro-specific changes.
Upgrade Guide
docs/oss/upgrading/upgrading-react-on-rails.md
Added upgrade sections for v16.3.0 and v16.4.0 covering version updates, removal of legacy Pro license key file in favor of env var, RSC template format change (.html.erb → .text.erb), and Shakapacker behavior simplifications.
Pro Documentation
docs/pro/updating.md
Expanded Pro upgrade guidance: Pro version alignment note, npm package roles (react-on-rails-pro vs react-on-rails-pro-node-renderer), gem sourcing guidance (move to rubygems.org), jwt ~> 2.7 requirement and update step, node renderer config rename (bundlePathserverBundleCachePath), and changed Pro default settings table with explicit migration instructions.
Pro Gem README
react_on_rails_pro/README.md
Updated compatibility matrix and installation example to reflect Pro 16.x (successor to 3.x/4.x) and corrected Gemfile example to ~> 16.0.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 hop hop Docs in order, tidy and spry,
Pro and OSS versions now side by side,
Gems, npm names, and configs all aligned,
I nibble the notes and leave no surprise behind! 🎉

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately summarizes the main change: adding documentation to bridge upgrade gaps for migrating from React on Rails 16.1.x to 16.4.0, which aligns with all the changes made.
Linked Issues check ✅ Passed The pull request successfully addresses all major objectives from issue #2762: adds v16.3.0 and v16.4.0 upgrade sections, explains Pro gem version alignment (3.x→16.x), documents npm package changes, provides JWT requirement guidance, includes changed defaults table, documents bundlePath→serverBundleCachePath rename, clarifies Pro npm package roles, and fixes stale version examples.
Out of Scope Changes check ✅ Passed All changes remain focused on documentation updates to address the upgrade gaps identified in issue #2762; no code changes or unrelated documentation modifications are present.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch jg/2762-upgrade-guide-gaps

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@greptile-apps
Copy link
Copy Markdown

greptile-apps Bot commented Mar 20, 2026

Greptile Summary

This 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 (16.3.0.md, 16.4.0.md), backfills the corresponding upgrade sections in the main OSS guide, and significantly expands the Pro upgrade guide with version-alignment context, the jwt ~> 2.7 prerequisite, the bundlePath → serverBundleCachePath rename, changed-defaults table, Gemfile redundancy note, and a new npm-packages clarification section.

Key observations:

  • All internal doc links resolve correctly (relative paths are consistent with the file structure)
  • The 16.3.0 release notes are missing the Pro users callout that the sibling 16.4.0.md includes, which could lead Pro users to use the wrong package names when following that file
  • The JWT requirement note says "16.x requires jwt ~> 2.7" but is placed under a section scoped to "16.4.0 or later" — the wording should be narrowed to match the section, or moved to a broader location
  • The version alignment table in docs/pro/updating.md uses "Old Version" / "New Version" column headers with inconsistent data types across rows, making it harder to parse at a glance
  • The README compatibility matrix fix (4.x → 16.x) and removal of the stale git-based install example are accurate and clean

Confidence Score: 4/5

  • Safe to merge; all issues are documentation style and clarity concerns with no broken links or factually incorrect content.
  • The changes are documentation-only and the core factual content (JWT dependency, bundlePath rename, changed defaults, version alignment) is verified against the gemspec and Gemfile.lock. The three flagged items are all clarity/consistency suggestions, not errors that would mislead users into breaking their apps.
  • docs/oss/upgrading/release-notes/16.3.0.md (missing Pro users note) and docs/pro/updating.md (JWT scope wording and version alignment table structure).

Important Files Changed

Filename Overview
docs/oss/upgrading/release-notes/16.3.0.md New release notes file for 16.3.0; accurate content but missing a Pro users callout directing them to use the correct package names (present in the sibling 16.4.0.md).
docs/oss/upgrading/release-notes/16.4.0.md New release notes file for 16.4.0; well-structured with clear breaking change callouts and a Pro users note directing to the Pro upgrade guide.
docs/oss/upgrading/upgrading-react-on-rails.md Added v16.3.0 and v16.4.0 upgrade sections in correct newest-first order; links to release notes and Pro guide are valid.
docs/pro/updating.md Adds version alignment section, JWT requirement, bundlePath rename, changed-defaults table, Gemfile redundancy note, and npm package clarification; minor wording inconsistency in the JWT scope ("16.x" vs. "16.4.0+") and confusing column semantics in the version alignment table.
react_on_rails_pro/README.md Fixes stale version numbers in the compatibility matrix (4.x → 16.x) and removes the outdated git-based install example; changes are accurate and consistent with the gemspec.

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
Loading

Last reviewed commit: "Docs: fill upgrade g..."

Comment thread docs/oss/upgrading/release-notes/16.3.0.md
Comment thread docs/pro/updating.md Outdated
Comment thread docs/pro/updating.md Outdated
Comment thread docs/oss/upgrading/release-notes/16.3.0.md
Comment thread docs/pro/updating.md Outdated
@claude
Copy link
Copy Markdown
Contributor

claude Bot commented Mar 20, 2026

Review: Docs — fill upgrade guide gaps for 16.1.x → 16.4.0 migration

Good documentation PR. I verified the technical claims against the codebase and they all check out:

  • JWT dependency (compatible with ~> 2.7): confirmed in react_on_rails_pro/react_on_rails_pro.gemspec:41
  • Changed defaults table: confirmed against react_on_rails_pro/lib/react_on_rails_pro/configuration.rb — DEFAULT_SSR_TIMEOUT = 5, DEFAULT_RENDERER_REQUEST_RETRY_LIMIT = 5, DEFAULT_RENDERER_FALLBACK_EXEC_JS = true
  • bundlePath to serverBundleCachePath rename: confirmed in react_on_rails_pro/spec/dummy/client/node-renderer.js and README
  • react_on_rails gem being redundant with Pro: confirmed — react_on_rails_pro.gemspec declares react_on_rails as a runtime dependency
  • Version alignment table (Pro 3.x/4.x to 16.x): accurate per CHANGELOG 16.2.0 entry
  • All PR numbers cited in release notes: cross-checked against CHANGELOG — all correct

Two inline comments:

  1. docs/oss/upgrading/release-notes/16.3.0.md — Missing Pro users callout after the package.json snippet (the same callout exists in the 16.4.0 release notes and should be added here for consistency)
  2. docs/pro/updating.md — 'Understanding the Pro npm packages' section is placed under the 16.4.0 upgrade steps; as general guidance it would be more discoverable higher up in the document

Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread docs/pro/updating.md Outdated
- 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>
@claude
Copy link
Copy Markdown
Contributor

claude Bot commented Mar 21, 2026

Review: Docs — fill upgrade guide gaps for 16.1.x → 16.4.0 migration

Good 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:

  • JWT dependency (~> 2.7): confirmed in react_on_rails_pro/react_on_rails_pro.gemspec:41
  • Changed defaults table (new values): confirmed against react_on_rails_pro/lib/react_on_rails_pro/configuration.rbDEFAULT_SSR_TIMEOUT = 5, DEFAULT_RENDERER_REQUEST_RETRY_LIMIT = 5, DEFAULT_RENDERER_FALLBACK_EXEC_JS = true
  • bundlePathserverBundleCachePath rename: confirmed in react_on_rails_pro/spec/dummy/client/node-renderer.js
  • react_on_rails being redundant with Pro: confirmed — react_on_rails_pro.gemspec declares react_on_rails as a runtime dependency
  • All PR numbers cited in the release notes: cross-checked against CHANGELOG — all correct

Three items worth a second look (inline comments posted):

  1. npmjs.org in the version alignment table should be npmjs.com (the canonical domain)
  2. JWT scope: the CHANGELOG shows JWT was introduced for license validation well before 16.4.0. Please confirm the ~> 2.7 lower-bound tightening is what's new in 16.4.0 (not the jwt dependency itself), and clarify the wording accordingly
  3. Changed defaults old values: the "Old Default (3.x)" column can't be verified from the current codebase — worth adding a brief note about the source (e.g., git history or internal knowledge) or a hedge like "verify against your Pro 3.x configuration"

Comment thread docs/pro/updating.md Outdated
Comment thread docs/pro/updating.md Outdated
Comment thread docs/pro/updating.md
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

+ "react-on-rails-pro": "^16.2.0",
- "@shakacode-tools/react-on-rails-pro-node-renderer": "16.1.1"
+ "react-on-rails-pro-node-renderer": "^16.2.0"

P1 Badge Remove 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".

Comment thread docs/pro/updating.md
- 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>
@claude
Copy link
Copy Markdown
Contributor

claude Bot commented Mar 21, 2026

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.

Comment thread docs/pro/updating.md

`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
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
```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.

Comment thread docs/pro/updating.md

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
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
- **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).

@justin808 justin808 merged commit fe5f261 into main Mar 21, 2026
22 checks passed
@justin808 justin808 deleted the jg/2762-upgrade-guide-gaps branch March 21, 2026 08:35
justin808 added a commit that referenced this pull request Mar 25, 2026
## 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>
justin808 added a commit that referenced this pull request Mar 30, 2026
## 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>
justin808 added a commit that referenced this pull request Apr 6, 2026
## 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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs: Upgrade guide gaps discovered migrating 16.1.2 → 16.4.0 (Pro + Node Renderer)

1 participant