Automate Pro generator gem/package swap and import updates

react_on_rails/lib/generators/react_on_rails/generator_helper.rb

@@ -34,7 +34,8 @@ def add_npm_dependencies(packages, dev: false)
                else
                  pj.manager.add(packages, exact: true)
                end
-      result ? true : false
+      # package_json#add can return nil for successful side-effect operations.
+      result != false
     rescue StandardError => e
       say_status :warning, "Could not add packages via package_json gem: #{e.message}", :yellow
       say_status :warning, "Will fall back to direct npm commands.", :yellow
@@ -151,20 +152,28 @@ def mark_pro_gem_installed!
     @pro_gem_installed = true
   end
 
-  # Check if Pro features should be enabled
-  # Returns true if --pro flag is set OR --rsc flag is set (RSC implies Pro)
+  # Check if first-class RSC Pro mode should be enabled.
+  # Returns true when --rsc-pro is set, or when users explicitly pass both --rsc and --pro.
+  #
+  # @return [Boolean] true if RSC Pro mode semantics should be applied
+  def use_rsc_pro_mode?
+    options[:rsc_pro] || (options[:rsc] && options[:pro])
+  end
+
+  # Check if Pro features should be enabled.
+  # Returns true if --pro, --rsc, or --rsc-pro is set (RSC implies Pro).
   #
   # @return [Boolean] true if Pro setup should be included
   def use_pro?
-    options[:pro] || options[:rsc]
+    options[:pro] || options[:rsc] || options[:rsc_pro]
   end
 
   # Check if RSC (React Server Components) should be enabled
-  # Returns true only if --rsc flag is explicitly set
+  # Returns true if --rsc or --rsc-pro is explicitly set
   #
   # @return [Boolean] true if RSC setup should be included
   def use_rsc?
-    options[:rsc]
+    options[:rsc] || options[:rsc_pro]
   end
 
   # Determine if the project is using rspack as the bundler.

react_on_rails/lib/generators/react_on_rails/install_generator.rb

@@ -57,13 +57,21 @@ class InstallGenerator < Rails::Generators::Base
       class_option :pro,
                    type: :boolean,
                    default: false,
-                   desc: "Install React on Rails Pro with Node Renderer. Default: false"
+                   desc: "Install React on Rails Pro with Node Renderer. " \
+                         "Combined with --rsc, uses --rsc-pro mode. Default: false"
 
       # --rsc
       class_option :rsc,
                    type: :boolean,
                    default: false,
-                   desc: "Install React Server Components support (includes Pro). Default: false"
+                   desc: "Install React Server Components support (includes Pro). " \
+                         "Combined with --pro, uses --rsc-pro mode. Default: false"
+
+      # --rsc-pro
+      class_option :rsc_pro,
+                   type: :boolean,
+                   default: false,
+                   desc: "Install first-class Pro RSC mode with matched Pro/RSC defaults. Default: false"
 
       # Hidden option: allows tests (and advanced users) to signal that Shakapacker
       # was just installed, triggering force-overwrite of shakapacker.yml with RoR's template.
@@ -88,6 +96,8 @@ class InstallGenerator < Rails::Generators::Base
       # Removed: --skip-shakapacker-install (Shakapacker is now a required dependency)
 
       SHAKAPACKER_YML_PATH = "config/shakapacker.yml"
+      HELLO_WORLD_ROUTE = "hello_world"
+      HELLO_SERVER_ROUTE = "hello_server"
       # Matches the stock `bin/dev` written by Rails 8.x. Rails 7.1 commonly
       # generated a foreman-based shell script instead, which stock_rails_bin_dev?
       # also recognizes so the React on Rails template can replace either variant.
@@ -190,7 +200,7 @@ def invoke_generators
         # --pretend/--force/--skip must be forwarded explicitly at each boundary.
         invoke "react_on_rails:base", [],
                { typescript: options.typescript?, redux: options.redux?, rspack: options.rspack?,
-                 pro: options.pro?, rsc: options.rsc?, new_app: options.new_app?,
+                 pro: use_pro?, rsc: use_rsc?, new_app: options.new_app?,
                  shakapacker_just_installed: shakapacker_just_installed?,
                  force: options[:force], skip: options[:skip], pretend: options[:pretend] }
 
@@ -202,7 +212,7 @@ def invoke_generators
           invoke "react_on_rails:react_with_redux", [], { typescript: options.typescript?,
                                                           invoked_by_install: true,
                                                           new_app: options.new_app?,
-                                                          rsc: options.rsc?,
+                                                          rsc: use_rsc?,
                                                           force: options[:force], skip: options[:skip],
                                                           pretend: options[:pretend] }
         elsif !use_rsc?
@@ -274,11 +284,12 @@ def installation_prerequisites_met?
         # it on a clean worktree. On a dirty tree, use the read-only pro_gem_installed?
         # check to catch a missing gem without triggering auto-install.
         if has_worktree_issues && use_pro? && !pro_gem_installed?
+          required_flag = pro_requirement_flag
           GeneratorMessages.add_error(<<~MSG.strip)
-            🚫 react_on_rails_pro gem is required for #{options[:rsc] ? '--rsc' : '--pro'} but is not installed.
+            🚫 react_on_rails_pro gem is required for #{required_flag} but is not installed.
             Auto-install was skipped because the worktree has uncommitted changes.
             Please add it manually:
-              gem 'react_on_rails_pro', '~> #{recommended_pro_gem_version}'
+              gem 'react_on_rails_pro', '#{pro_gem_version_requirement}'
             Then run: bundle install
           MSG
           return false
@@ -382,7 +393,7 @@ def add_bin_scripts
         if preserve_existing_bin_dev?
           if use_rsc? && !options.redux? && !options.new_app?
             say_status :warn,
-                       'Custom bin/dev detected: update DEFAULT_ROUTE to "hello_server" manually for --rsc',
+                       "Custom bin/dev detected: update DEFAULT_ROUTE to \"#{HELLO_SERVER_ROUTE}\" manually for --rsc",
                        :yellow
           end
         else
@@ -463,10 +474,10 @@ def add_post_install_message
         # Determine what route and component will be created by the generator
         if use_rsc? && !options.redux?
           # RSC without Redux: HelloServer replaces HelloWorld
-          route = "hello_server"
+          route = HELLO_SERVER_ROUTE
           component_name = "HelloServer"
         else
-          route = "hello_world"
+          route = HELLO_WORLD_ROUTE
           component_name = options.redux? ? "HelloWorldApp" : "HelloWorld"
         end
 
@@ -478,6 +489,7 @@ def add_post_install_message
                                      shakapacker_just_installed: shakapacker_just_installed?,
                                      landing_page: options.new_app? && new_app_root_route_available?
                                    ))
+        GeneratorMessages.add_info(rsc_pro_verification_message) if use_rsc_pro_mode?
       end
 
       def shakapacker_setup_incomplete?
@@ -491,7 +503,9 @@ def recovery_install_command
         flags << "--typescript" if options.typescript?
         flags << "--rspack" if options.rspack?
 
-        if use_rsc?
+        if use_rsc_pro_mode?
+          flags << "--rsc-pro"
+        elsif options.rsc?
           flags << "--rsc"
         elsif options.pro?
           flags << "--pro"
@@ -500,6 +514,17 @@ def recovery_install_command
         ["rails generate react_on_rails:install", *flags].join(" ")
       end
 
+      def rsc_pro_verification_message
+        <<~MSG
+
+          🔎 RSC Pro Verification:
+          ─────────────────────────────────────────────────────────────────────────
+          1. Start all processes: #{Rainbow('bin/dev').cyan}
+          2. Visit: #{Rainbow("http://localhost:<port>/#{HELLO_SERVER_ROUTE}").cyan.underline}
+          3. Confirm the page streams and the Like button hydrates on click.
+        MSG
+      end
+
       def recovery_working_tree_lines
         [
           "If this run created or changed files, clean up your working tree before rerunning",

react_on_rails/lib/generators/react_on_rails/js_dependency_manager.rb

@@ -125,6 +125,10 @@ module JsDependencyManager
         react-on-rails-rsc
       ].freeze
 
+      # RSC package releases follow the React 19.0.x line (independent from gem versioning).
+      RSC_REACT_VERSION_RANGE = "~19.0.4"
+      RSC_PACKAGE_VERSION_PIN = "19.0.4"
+
       private
 
       def setup_js_dependencies
@@ -218,7 +222,7 @@ def add_react_dependencies
         # RSC requires React 19.0.x specifically (not 19.1.x or later)
         # Pin to ~19.0.4 to allow patch updates while staying within 19.0.x
         react_deps = if respond_to?(:use_rsc?) && use_rsc?
-                       %w[react@~19.0.4 react-dom@~19.0.4 prop-types]
+                       ["react@#{RSC_REACT_VERSION_RANGE}", "react-dom@#{RSC_REACT_VERSION_RANGE}", "prop-types"]
                      else
                        REACT_DEPENDENCIES
                      end
@@ -383,13 +387,29 @@ def pro_packages_with_version
 
       def add_rsc_dependencies
         say "Installing React Server Components dependencies..."
-        return if add_packages(RSC_DEPENDENCIES)
+        rsc_packages, used_version_pins = rsc_packages_with_version
+        return if add_packages(rsc_packages)
+
+        manual_install_packages = rsc_packages
+        if used_version_pins
+          warning_msg = "Could not install version-pinned RSC dependency. Retrying latest available package."
+          say_status :warning,
+                     warning_msg,
+                     :yellow
+          GeneratorMessages.add_warning(
+            "Warning: #{warning_msg} " \
+            "The installed react-on-rails-rsc version may not match the expected compatibility pin."
+          )
+          return if add_packages(RSC_DEPENDENCIES)
+
+          manual_install_packages = RSC_DEPENDENCIES
+        end
 
         GeneratorMessages.add_warning(<<~MSG.strip)
           ⚠️  Failed to add React Server Components dependencies.
 
           You can install them manually by running:
-            npm install #{RSC_DEPENDENCIES.join(' ')}
+            npm install #{manual_install_packages.join(' ')}
         MSG
       rescue StandardError => e
         GeneratorMessages.add_warning(<<~MSG.strip)
@@ -400,6 +420,12 @@ def add_rsc_dependencies
         MSG
       end
 
+      # Returns [pinned_packages, used_version_pins]. used_version_pins is always true here;
+      # subclasses may override to return [packages, false] when pinning should be skipped.
+      def rsc_packages_with_version
+        [RSC_DEPENDENCIES.map { |pkg| "#{pkg}@#{RSC_PACKAGE_VERSION_PIN}" }, true]
+      end
+
       def remove_base_package_if_present
         pj = package_json
         return unless pj