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

[justin808]

Context

While upgrading a large production Rails app (React 18, Shakapacker 9.5, react_on_rails_pro with Node Renderer) from react_on_rails 16.1.2 → 16.4.0, we found several documentation gaps that made the upgrade harder than necessary. Filing them together since they all relate to the same upgrade path.

---

1. No upgrade guide covering 16.1.x → 16.4.0

The upgrade docs only cover up to 16.2.x. There's no guidance for 16.3.0 or 16.4.0 changes. Users upgrading from any 16.1.x version have to piece together what's needed from the CHANGELOG alone.

Suggestion: Add upgrade sections for 16.3.0 and 16.4.0 to the upgrade guide, even if the changes are minor.

---

2. Pro gem version jump from 3.x → 16.x is undocumented

react_on_rails_pro jumped from version 3.3.x to 16.x.x (aligning with the core gem version numbering). There's no migration guide or even a mention that this renumbering happened. Users on 3.3.x have no obvious path to 16.4.0 — it looks like a completely different gem.

Suggestion: Add a note in the upgrade guide and CHANGELOG explaining the version alignment, e.g., "react_on_rails_pro 16.x is the successor to 3.x, version numbers were aligned with the core gem."

---

3. Node renderer npm package rename not in migration steps

The node renderer package was renamed from @shakacode-tools/react-on-rails-pro-node-renderer to react-on-rails-pro-node-renderer (now on public npm). This is a critical migration step for Pro users with SSR, but it's not called out in any upgrade guide or migration checklist. Users only discover it by noticing the old package doesn't have a matching version.

Suggestion: Add explicit migration step: "Replace @shakacode-tools/react-on-rails-pro-node-renderer with react-on-rails-pro-node-renderer in your package.json."

---

4. Pro gem source change (private GitHub Packages → rubygems.org) not documented

react_on_rails_pro was previously distributed via a private GitHub Packages source (rubygems.pkg.github.com/shakacode-tools). It's now available on rubygems.org. Users still pointing to the private source won't find version 16.4.0 there, and there's no note about removing the private source block from their Gemfile.

Suggestion: Add migration step: "Remove the private shakacode-tools source block from your Gemfile. react_on_rails_pro is now available on rubygems.org."

---

5. JWT >= 2.7 requirement not called out as potential conflict

react_on_rails_pro 16.4.0 depends on jwt >= 2.7. Many Rails apps pin jwt to older versions (e.g., 2.2.x) for compatibility with other gems (OAuth, etc.). This version requirement isn't mentioned in the upgrade guide and causes a Bundler::VersionConflict that users have to debug themselves.

Suggestion: Add to upgrade prerequisites: "react_on_rails_pro 16.4.0 requires jwt >= 2.7. If your Gemfile pins jwt to an older version, you'll need to upgrade it."

---

6. Default config value changes not prominently documented

Several Pro configuration defaults changed between 3.3.x and 16.4.0:

• ssr_timeout: 20s → 5s
• renderer_request_retry_limit: default is now 5 (was lower)
• renderer_use_fallback_exec_js: default is now true

Users who relied on previous defaults without explicitly setting values will get different behavior after upgrading. These changes aren't called out in any "what changed" section.

Suggestion: Add a "Changed Defaults" table to the upgrade guide listing old vs. new default values for Pro configuration.

---

7. bundlePath → serverBundleCachePath rename only in deprecation notes

The node renderer config rename from bundlePath to serverBundleCachePath is mentioned in the CHANGELOG deprecation section but not in the step-by-step migration. Users scanning the upgrade guide for "what do I need to change in my node renderer config" won't find it.

Suggestion: Add to migration steps: "In your node renderer config file, rename bundlePath to serverBundleCachePath."

---

8. Relationship between react-on-rails-pro and react-on-rails-pro-node-renderer npm packages unclear

16.4.0 introduces two separate npm packages:

• react-on-rails-pro — client-side Pro features (immediate hydration, RSC, etc.)
• react-on-rails-pro-node-renderer — server-side Node.js renderer

The docs don't clearly explain when you need one vs. both. For example, if you only use the Node Renderer for SSR and don't use RSC or immediate hydration, do you need react-on-rails-pro? The answer isn't obvious.

Suggestion: Add a section explaining the two packages, their purposes, and when each is needed.

---

9. Pro gem README has stale version example

The react_on_rails_pro gem README (inside the 16.4.0 gem itself) shows:

gem 'react_on_rails_pro', '~> 4.0'

This version doesn't exist — the gem jumped from 3.x to 16.x. The example should show '~> 16.0' or '16.4.0'.

Location: react_on_rails_pro-16.4.0/README.md, Getting Started section.

---

Environment

• Rails 8.0.4, Ruby 3.2
• react_on_rails 16.1.2 → 16.4.0
• react_on_rails_pro 3.3.1 → 16.4.0
• Shakapacker 9.5.0
• Node.js 22.13.0
• Using Rspack (primary) + Webpack (legacy fallback)
• Pro Node Renderer for SSR

[justin808]

10. Docs should note that react_on_rails gem is redundant when using react_on_rails_pro

Since react_on_rails_pro 16.4.0 declares react_on_rails = 16.4.0 as a hard dependency, users don't need (and shouldn't have) a separate gem "react_on_rails" line in their Gemfile when using Pro. This isn't mentioned anywhere in the upgrade guide or Pro README.

Having both lines can cause confusion about which controls the version, and makes it unclear whether the explicit line is needed for some reason.

Suggestion: Add a note in the Pro getting-started docs: "If you use react_on_rails_pro, you do not need a separate gem 'react_on_rails' line — it is automatically included as a dependency."

[justin808]

11. Upgrade guide should mention removing private npm registry config

When migrating from @shakacode-tools/react-on-rails-pro-node-renderer (private npm) to react-on-rails-pro-node-renderer (public npm), users should also remove any .npmrc files that configured the @shakacode-tools private registry scope. The upgrade guide doesn't mention this cleanup step.

Suggestion: Add to migration steps: "If you have an .npmrc with @shakacode-tools:registry=https://npm.pkg.github.com, remove it — the node renderer package is now on the public npm registry."

[justin808]

12. Upgrade guide must cover switching imports from react-on-rails to react-on-rails-pro

The react-on-rails-pro npm package README clearly states:

Important: When using the react_on_rails_pro Ruby gem, you must use this package (react-on-rails-pro) instead of react-on-rails. If the Pro gem detects the base react-on-rails npm package at runtime, it will raise an error.

And:

This package wraps and extends the base react-on-rails package. You only need to install react-on-rails-pro — the base package is included as a dependency.

However, none of this is in the upgrade guide. Pro users upgrading from 3.x (where the npm package was @shakacode-tools/react-on-rails-pro-node-renderer and imports were from react-on-rails) have no guidance on this critical migration step. We had to discover it by reading the npm package README.

The upgrade guide should include these explicit steps:

1. package.json: Remove react-on-rails — only react-on-rails-pro is needed (it depends on react-on-rails internally)
2. All imports: Change import ... from 'react-on-rails' → import ... from 'react-on-rails-pro'
3. All imports: Change import ... from 'react-on-rails/client' → import ... from 'react-on-rails-pro/client'

Similarly for the Ruby side (related to issue #10 above): the react_on_rails gem line in the Gemfile is redundant when using react_on_rails_pro, since the Pro gem declares it as an exact dependency.

Suggestion: Add a "Pro Users: Package Migration" section to the upgrade guide with all three steps above, plus the Gemfile cleanup. This is the single most impactful missing piece — without it, Pro users will get runtime errors after upgrading.