🎯 Objective

Unify versioning across all React on Rails packages and gems by migrating React on Rails Pro from version 4.x to 16.x to match the main react_on_rails package. This eliminates confusion and ensures guaranteed compatibility through exact version matching.

📊 Current State

Before:

• react_on_rails gem: 16.1.1
• react-on-rails npm: 16.1.1
• react-on-rails-pro npm: 16.1.1
• react_on_rails_pro gem: 4.0.0 ❌
• @shakacode-tools/react-on-rails-pro-node-renderer npm: 4.0.0 ❌

This version discrepancy causes:

• User confusion ("Why is Pro at 4.0 when main is at 16.1?")
• Unclear compatibility expectations
• Complex release coordination
• Inconsistent versioning across the ecosystem

🎯 Proposed Changes

1. Version Unification

• Bump react_on_rails_pro gem: 4.0.0 → 16.1.1
• Bump @shakacode-tools/react-on-rails-pro-node-renderer npm: 4.0.0 → 16.1.1
• Keep PROTOCOL_VERSION independent at 2.0.0 (only changes on protocol updates)

2. Enforce Exact Version Matching

Enhance ReactOnRails::VersionChecker to:

• ✅ Check for exact versions (reject ^, ~, >=, etc.)
• ✅ Validate react-on-rails OR react-on-rails-pro package versions
• ✅ Validate @shakacode-tools/react-on-rails-pro-node-renderer version
• ✅ Warn if both main and Pro packages are installed
• ✅ Raise errors in dev/test, log in production

3. Update Dependencies

• Pro gem requires exact version match: s.add_runtime_dependency "react_on_rails", ReactOnRailsPro::VERSION
• Previously: s.add_runtime_dependency "react_on_rails", ">= 16.0.0"

✅ Benefits

1. Simplified Mental Model: "Everything uses version X.Y.Z"
2. Guaranteed Compatibility: Exact version matching prevents drift
3. Easier Support: Single version number to reference
4. Clearer Documentation: No version mapping needed
5. Unified Branding: Consistent versioning across ecosystem

🔍 Implementation Details

Version Checker Enhancements

Checks performed on Rails initialization:

# 1. Detect if both packages present
if has_both_packages?
  warn "Only install react-on-rails-pro (includes main as dependency)"
end

# 2. Check for exact version (no wildcards)
if package_version.semver_wildcard?
  error "Must use exact version: yarn add [email protected] --exact"
end

# 3. Check version match
if package_version != gem_version
  error "Package version 16.0.0 does not match gem version 16.1.1"
end

# 4. Check node-renderer version (Pro only)
if node_renderer_version != pro_gem_version
  error "Node renderer version must match Pro gem version"
end

Error Handling:

• Dev/Test environments: Raises ReactOnRails::Error (blocking)
• Production environment: Logs error (non-blocking, prevents deployment failures)

PROTOCOL_VERSION Independence

PROTOCOL_VERSION remains at 2.0.0 and is independent from the main version:

• Purpose: Communication protocol compatibility between Rails gem and Node renderer
• Only incremented when protocol changes (e.g., new request/response format)
• Provides clear separation between package version and protocol compatibility

📝 Files Modified

• lib/react_on_rails/version_checker.rb - Enhanced version checking
• react_on_rails_pro/lib/react_on_rails_pro/version.rb - 4.0.0 → 16.1.1
• react_on_rails_pro/package.json - 4.0.0 → 16.1.1
• react_on_rails_pro/react_on_rails_pro.gemspec - Exact version dependency

🚀 Future Release Process

Going forward, all versions will be synchronized:

1. Use main release script (rakelib/release.rake)
2. Single version bump updates all packages and gems
3. No separate Pro release script needed

⚠️ Breaking Changes

• No backward compatibility: Users must upgrade both gem and NPM packages together
• Exact versions required: Semver wildcards (^, ~) will be rejected
• Pro gem dependency: Now requires exact main gem version match

📚 Related

• Current main version: 16.1.1
• Current protocol version: 2.0.0
• Package manager: Yarn Classic v1
• Ruby version requirement: >= 3.0
• Node version requirement: >= 18