React on Rails 16.2.0 Release Notes

React on Rails 16.2.0 is a major release focused on clear separation between the open-source core and React on Rails Pro. This release simplifies configuration by making Pro features automatic for licensed users, adds Rspack support for faster builds, and includes critical security fixes for React Server Components.

Upgrading from 16.1.x to 16.2.0

Update your gem and npm package versions:

# Gemfile
gem "react_on_rails", "16.2.0"
gem "shakapacker", "9.0.0"  # or 8.2.0+ for existing projects

// package.json
{
  "dependencies": {
    "react-on-rails": "16.2.0",
    "shakapacker": "9.0.0"
  }
}

Then run bundle install and your package manager's install command.

Important: The shakapacker gem and npm package versions must match exactly.

Version Compatibility

Note: While the gem supports Ruby 3.0+ and Node.js 18+, CI only tests against Ruby 3.2+ and Node.js 20+. Using lower versions may work but is not continuously tested.

Breaking Changes

1. config.immediate_hydration Configuration Removed

The config.immediate_hydration setting in config/initializers/react_on_rails.rb has been removed. Immediate hydration is now automatically enabled for React on Rails Pro users and automatically disabled for non-Pro users.

Migration steps:

1. Remove any config.immediate_hydration = true or config.immediate_hydration = false lines from your initializer
2. Pro users: No action needed - immediate hydration is now enabled automatically
3. Non-Pro users: No action needed - standard hydration behavior continues

Component-level overrides still work:

# Override for a specific component
<%= react_component("MyComponent", props, immediate_hydration: false) %>

# Override for a specific store
<%= redux_store("MyStore", props: store_props, immediate_hydration: true) %>

Note: If a non-Pro user explicitly sets immediate_hydration: true, a warning will be logged and the value will be overridden to false.

PR 1997 by AbanoubGhadban.

2. Pro-Only Methods Throw Runtime Errors Without Pro Package

Several methods in the react-on-rails npm package now throw runtime errors if called without the Pro package. Calling these methods will throw: "<method> requires react-on-rails-pro package":

• getOrWaitForComponent()
• getOrWaitForStore()
• getOrWaitForStoreGenerator()
• reactOnRailsStoreLoaded()
• streamServerRenderedReactComponent()
• serverRenderRSCReactComponent()

Migration (if using these methods):

// Before
import ReactOnRails from 'react-on-rails';

// After
import ReactOnRails from 'react-on-rails-pro';

Note: If you're not using any of these methods, no changes are required.

3. RSC Configurations Moved to Pro Gem

React Server Components configurations have moved from ReactOnRails.configure to ReactOnRailsPro.configure:

# Before
ReactOnRails.configure do |config|
  config.rsc_bundle_js_file = "rsc-bundle.js"
  config.react_server_client_manifest_file = "react-server-client-manifest.json"
  config.react_client_manifest_file = "react-client-manifest.json"
end

# After
ReactOnRailsPro.configure do |config|
  config.rsc_bundle_js_file = "rsc-bundle.js"
  config.react_server_client_manifest_file = "react-server-client-manifest.json"
  config.react_client_manifest_file = "react-client-manifest.json"
end

4. Streaming View Helpers Moved to Pro Gem

The following view helpers are now only available in React on Rails Pro:

• stream_react_component - Progressive SSR using React 18+ streaming
• rsc_payload_react_component - RSC payload rendering

5. Strict Version Validation at Boot Time

Applications now fail to boot (instead of logging warnings) when package.json is misconfigured with:

• Wrong versions
• Missing packages
• Semver wildcards (^, ~, >, <, *)

Migration:

// Before (will fail)
{
  "dependencies": {
    "react-on-rails": "^16.2.0"
  }
}

// After (correct)
{
  "dependencies": {
    "react-on-rails": "16.2.0"
  }
}

PR 1881 by AbanoubGhadban.

6. Node Renderer Version Validation (Pro Only)

The remote node renderer now validates gem version at request time. Version mismatches in development return 412 Precondition Failed (production allows with warning).

Migration: Ensure react_on_rails_pro gem and @shakacode-tools/react-on-rails-pro-node-renderer package versions match.

New Features

Rspack Support

Added --rspack flag to react_on_rails:install generator for significantly faster builds (~20x improvement with SWC):

rails generate react_on_rails:install --rspack

Includes a bin/switch-bundler utility to switch between webpack and Rspack post-installation.

PR 1852 by justin808.

Shakapacker 9.0+ Private Output Path Integration

React on Rails now automatically detects and integrates with Shakapacker 9.0+ private_output_path configuration, eliminating manual configuration synchronization for server bundles.

PR 2028 by justin808.

CSP Nonce Support for Console Replay

When Rails CSP is configured, the console replay script automatically includes the nonce attribute, allowing it to execute under restrictive CSP policies like script-src: 'self'.

PR 2059 by justin808.

Smart Error Messages with Actionable Solutions

New intelligent Ruby-side error handling with:

• Fuzzy matching for component name typos
• Environment-specific debugging suggestions
• Color-coded error formatting
• Detailed troubleshooting guides

See the Improved Error Messages guide for details.

PR 1934 by justin808.

Service Dependency Checking for bin/dev

Optional .dev-services.yml configuration to validate required external services (Redis, PostgreSQL, etc.) are running before bin/dev starts:

# .dev-services.yml
services:
  - name: redis
    check: redis-cli ping
    start: redis-server

PR 2098 by justin808.

Security

Critical: React Server Components Vulnerabilities Fixed

Action Required: React on Rails Pro users using RSC should upgrade immediately to get React 19.0.3 and react-on-rails-rsc 19.0.4.

Upgraded React to v19.0.3 and react-on-rails-rsc to v19.0.4 to fix three security vulnerabilities:

PR 2233 by AbanoubGhadban.

Development Dependencies Security

Addressed 58 Dependabot vulnerabilities in dev/test dependencies including critical issues in webpack, nokogiri, activestorage, and rack.

PR 2261 by ihabadham.

Command Injection Protection

Added security hardening to prevent potential command injection in package manager commands.

PR 1881 by AbanoubGhadban.

Bug Fixes

• Component Registration: Fixed "component not registered" error that could occur when components were referenced before registration completed. PR 2295 by AbanoubGhadban
• webpack-cli Compatibility: Fixed compatibility with webpack-dev-server v5. PR 2291 by AbanoubGhadban
• Hydration Mismatch: Fixed errors when reactOnRailsPageLoaded() was called multiple times. PR 2211 by justin808
• Rails 5.2-6.0 Compatibility: Added polyfill for compact_blank method. PR 2058 by justin808
• connection_pool 3.0+ Compatibility: Fixed ArgumentError with newer connection_pool versions. PR 2125 by justin808

See the CHANGELOG for additional bug fixes and improvements.

Common Upgrade Issues

"Cannot find module 'react-on-rails-pro'"

Symptom: Application fails to start with module not found error.

Cause: You're using Pro-only methods but haven't installed the Pro package.

Solution:

npm install react-on-rails-pro
# or
yarn add react-on-rails-pro
# or
pnpm add react-on-rails-pro

Version Mismatch Boot Failure

Symptom: Application fails to boot with version validation error.

Cause: package.json has semver wildcards or mismatched versions.

Solution: Use exact versions matching your installed gem:

# Check gem version
bundle show react_on_rails

# Update package.json to match (no ^, ~, or *)

Immediate Hydration Config Warning

Symptom: Deprecation warning about config.immediate_hydration in logs.

Cause: The global config option is now deprecated and has no effect.

Solution: Remove config.immediate_hydration from your initializer. The setting is now automatic (enabled for Pro users, disabled for non-Pro). Use component-level overrides if needed.

Related Resources

• Changelog
• Configuration Reference
• React on Rails Pro