react_on_rails 16.4.0.rc.9 → 16.4.0.rc.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdb10a9ed4626714e8eb70c05076bed77f57d4a7470a6a4e506505ee7e408c7b
-  data.tar.gz: 1e7050122dc2c9feb0a2da0bc4152fd450a31cbc51a6229486345eed3dd08dae
+  metadata.gz: cdd0253666ff913084d12f9f5b3f24b41f0f33ed418165f54a5d038cb567012d
+  data.tar.gz: 510bcdc628f66dd6c9ddfae7be24582fef28ea35c263440e86a640b419bff379
 SHA512:
-  metadata.gz: fa093cb5e5ac6ac0c6b69fae0de4e998e0e90b56b71c8290e421cc553bdd6a4748afafffd4cdbe8aa56f95f3fa14956eab1cf4f08b7c38cd5d29d5e3798ab0d0
-  data.tar.gz: 4b00fb4d7606b6276f1cc23b3e7766c74b3cc4ba58b3f4e9162918714dbc9a400f3f470c7d1ed1c100678179abc11aa3fa6f94a75a6861e4e926fd796c989976
+  metadata.gz: fa0ec02748d25524f70fa7fe73803fc25c8c73249a17b953517ab3b226fa2101efc0443b3bab201737711f91d4a4f4d9d280e29005c28b505ae3d2d6d4bda153
+  data.tar.gz: 365c80cbf379d64e9c74958e96334fe494d2f9770f8fa0f1b01eae03f89e11fd08590459bbe3a021f6a4e3ff697a7ad78bcfa9fd93ac0646ada6007f6d471b8a

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    react_on_rails (16.4.0.rc.9)
+    react_on_rails (16.4.0.rc.10)
       addressable
       connection_pool
       execjs (~> 2.5)

data/lib/generators/react_on_rails/base_generator.rb

@@ -2,6 +2,7 @@
 
 require "rails/generators"
 require "fileutils"
+require "erb"
 require_relative "generator_messages"
 require_relative "generator_helper"
 require_relative "js_dependency_manager"
@@ -47,6 +48,56 @@ module ReactOnRails
                    default: false,
                    hide: true
 
+      # Keep this map in sync with templates under:
+      # lib/generators/react_on_rails/templates/**/config/webpack/*.tt
+      MANAGED_WEBPACK_FILE_TEMPLATES = {
+        "clientWebpackConfig.js" => "base/base/config/webpack/clientWebpackConfig.js.tt",
+        "commonWebpackConfig.js" => "base/base/config/webpack/commonWebpackConfig.js.tt",
+        "test.js" => "base/base/config/webpack/test.js.tt",
+        "development.js" => "base/base/config/webpack/development.js.tt",
+        "production.js" => "base/base/config/webpack/production.js.tt",
+        "serverWebpackConfig.js" => "base/base/config/webpack/serverWebpackConfig.js.tt",
+        "rscWebpackConfig.js" => "rsc/base/config/webpack/rscWebpackConfig.js.tt",
+        "ServerClientOrBoth.js" => "base/base/config/webpack/ServerClientOrBoth.js.tt",
+        # Legacy filename generated by older React on Rails versions.
+        # We compare against the current options (including --pro/--rsc); if those
+        # don't match the original generation, cleanup intentionally preserves files.
+        "generateWebpackConfigs.js" => "base/base/config/webpack/ServerClientOrBoth.js.tt"
+      }.freeze
+
+      # Keep these helper delegates in sync with ERB calls in managed webpack
+      # templates. This is the intended template-facing API; missing delegates
+      # intentionally fail rendering and keep cleanup conservative by treating
+      # files as non-removable.
+      TemplateRenderContext = Struct.new(:generator, :config) do
+        def erb_binding
+          binding
+        end
+
+        def add_documentation_reference(*args)
+          generator.__send__(:add_documentation_reference, *args)
+        end
+
+        def use_pro?
+          generator.__send__(:use_pro?)
+        end
+
+        def use_rsc?
+          generator.__send__(:use_rsc?)
+        end
+
+        def shakapacker_version_9_or_higher?
+          generator.__send__(:shakapacker_version_9_or_higher?)
+        end
+      end
+
+      REMOVABLE_WEBPACK_FILES = (MANAGED_WEBPACK_FILE_TEMPLATES.keys +
+        %w[webpack.config.js]).freeze
+      DOCS_REFERENCE_MESSAGE = "// The source code including full typescript support is available at:"
+      TEMPLATE_RENDER_FAILED = Object.new.freeze # unique sentinel compared by identity via .equal?
+      private_constant :MANAGED_WEBPACK_FILE_TEMPLATES, :REMOVABLE_WEBPACK_FILES, :TemplateRenderContext,
+                       :DOCS_REFERENCE_MESSAGE, :TEMPLATE_RENDER_FAILED
+
       def add_hello_world_route
         # RSC uses HelloServer instead of HelloWorld, but Redux still needs hello_world route
         return if use_rsc? && !options.redux?
@@ -70,9 +121,9 @@ module ReactOnRails
                         .env.example
                         bin/shakapacker-precompile-hook]
 
-        # HelloServer uses the hello_world layout so React on Rails can inject generated
-        # packs without requiring a hardcoded application.js pack entry.
-        base_files << "app/views/layouts/hello_world.html.erb"
+        # react_on_rails_default layout provides empty pack tags so React on Rails can
+        # inject generated packs without requiring a hardcoded application.js pack entry.
+        base_files << "app/views/layouts/react_on_rails_default.html.erb"
 
         # HelloWorld controller only when not using RSC (RSC uses HelloServer)
         # Exception: Redux still needs the HelloWorld controller even with RSC
@@ -104,6 +155,10 @@ module ReactOnRails
       end
 
       def copy_webpack_config
+        # Cleanup must run before writing new webpack/rspack configs so we only
+        # evaluate pre-existing stale entries, never files generated in this run.
+        cleanup_stale_webpack_config_dir_for_rspack
+
         say "Adding #{using_rspack? ? 'Rspack' : 'Webpack'} config"
         base_path = "base/base"
         base_files = %w[babel.config.js
@@ -114,9 +169,7 @@ module ReactOnRails
                         config/webpack/production.js
                         config/webpack/serverWebpackConfig.js
                         config/webpack/ServerClientOrBoth.js]
-        config = {
-          message: "// The source code including full typescript support is available at:"
-        }
+        config = { message: DOCS_REFERENCE_MESSAGE }
         base_files.each do |file|
           template("#{base_path}/#{file}.tt", destination_config_path(file), config)
         end
@@ -183,7 +236,7 @@ module ReactOnRails
         add_configure_minitest_to_compile_assets(test_helper) if File.exist?(test_helper)
       end
 
-      CONFIGURE_RSPEC_TO_COMPILE_ASSETS = <<-STR.strip_heredoc
+      CONFIGURE_RSPEC_TO_COMPILE_ASSETS = <<~STR
         RSpec.configure do |config|
           # Ensure that if we are running js tests, we are using latest webpack assets
           # This will use the defaults of :js and :server_rendering meta tags
@@ -193,7 +246,7 @@ module ReactOnRails
         end
       STR
 
-      CONFIGURE_MINITEST_TO_COMPILE_ASSETS = <<-STR.strip_heredoc
+      CONFIGURE_MINITEST_TO_COMPILE_ASSETS = <<~STR
         # Ensure that tests run against fresh webpack assets.
         ActiveSupport::TestCase.setup do
           ReactOnRails::TestHelper.ensure_assets_compiled
@@ -219,7 +272,7 @@ module ReactOnRails
           existing_content = File.read(webpack_config_path)
 
           # Check if it's the standard Shakapacker config that we can safely replace
-          if standard_shakapacker_config?(existing_content)
+          if standard_shakapacker_config?(existing_content, strip_comments: true)
             # Remove the file first to avoid conflict prompt, then recreate it
             remove_file(webpack_config_path, verbose: false)
             # Show what we're doing
@@ -273,25 +326,265 @@ module ReactOnRails
         end
       end
 
-      def standard_shakapacker_config?(content)
+      def cleanup_stale_webpack_config_dir_for_rspack
+        return unless cleanup_stale_webpack_config_dir?
+
+        webpack_config_relative_dir = "config/webpack"
+        all_entries = stale_webpack_config_entries
+        unless all_entries
+          say_status :warning,
+                     "Keeping #{webpack_config_relative_dir}; could not read directory entries " \
+                     "(permission denied or path changed)",
+                     :yellow
+          return
+        end
+        if all_entries.empty?
+          say_status :skip, "#{webpack_config_relative_dir} (empty directory, leaving as-is)", :yellow
+          return
+        end
+
+        return warn_dotfiles_only_webpack_dir(webpack_config_relative_dir, all_entries) if all_dotfiles?(all_entries)
+
+        # We only clean up known top-level files. Any directory or unknown entry is
+        # treated as non-removable so we don't recurse into user-managed content.
+        non_removable_entries = non_removable_webpack_entries(all_entries)
+        removable_entries = removable_webpack_entries(all_entries)
+        if non_removable_entries.empty?
+          remove_stale_webpack_dir(webpack_config_relative_dir)
+          return
+        end
+
+        if all_dotfiles?(non_removable_entries)
+          handle_dotfile_only_non_removable_entries(
+            webpack_config_relative_dir,
+            removable_entries,
+            non_removable_entries
+          )
+          return
+        end
+
+        removed_entries = remove_stale_webpack_files(webpack_config_relative_dir, removable_entries)
+        warn_non_removable_webpack_entries(webpack_config_relative_dir, non_removable_entries, removed_entries)
+      end
+
+      def remove_stale_webpack_dir(webpack_config_relative_dir)
+        # Thor's remove_dir uses paths relative to destination_root.
+        # TOCTOU: a file created between the removability check and remove_dir
+        # would be deleted. Acceptable for this generator cleanup path.
+        remove_dir(webpack_config_relative_dir, verbose: false)
+        say_status :remove,
+                   "#{webpack_config_relative_dir} (stale webpack configs after switching to --rspack)",
+                   :green
+      end
+
+      def handle_dotfile_only_non_removable_entries(
+        webpack_config_relative_dir,
+        removable_entries,
+        non_removable_entries
+      )
+        removed_entries = remove_stale_webpack_files(webpack_config_relative_dir, removable_entries)
+        warn_dotfiles_in_webpack_dir(webpack_config_relative_dir, non_removable_entries, removed_entries)
+      end
+
+      def cleanup_stale_webpack_config_dir?
+        using_rspack? && Dir.exist?(stale_webpack_config_dir)
+      end
+
+      def all_dotfiles?(entries)
+        entries.any? && entries.all? { |entry| entry.start_with?(".") }
+      end
+
+      def warn_dotfiles_only_webpack_dir(webpack_config_relative_dir, all_entries)
+        say_status :warning,
+                   "Keeping #{webpack_config_relative_dir}; only dotfiles found: " \
+                   "#{all_entries.join(', ')}",
+                   :yellow
+      end
+
+      def warn_non_removable_webpack_entries(webpack_config_relative_dir, non_removable_entries, removed_entries = [])
+        non_dotfile_entries = non_removable_entries.reject { |entry| entry.start_with?(".") }
+        dotfiles = non_removable_entries.select { |entry| entry.start_with?(".") }
+        non_removable_directories, non_removable_files = non_dotfile_entries.partition do |entry|
+          directory_entry?(entry)
+        end
+
+        non_removable_sections = []
+        non_removable_sections << "files: #{non_removable_files.join(', ')}" if non_removable_files.any?
+        if non_removable_directories.any?
+          non_removable_sections << "directories: #{non_removable_directories.join(', ')}"
+        end
+        non_removable_sections << "dotfiles: #{dotfiles.join(', ')}" if dotfiles.any?
+
+        non_removable_sections_message = non_removable_sections.join("; ")
+        removed_entries_message = if removed_entries.any?
+                                    " Removed stale managed files: #{removed_entries.join(', ')}."
+                                  else
+                                    ""
+                                  end
+        say_status :warning,
+                   "Keeping #{webpack_config_relative_dir}; " \
+                   "custom/non-removable entries detected: #{non_removable_sections_message}." \
+                   "#{removed_entries_message}",
+                   :yellow
+      end
+
+      def directory_entry?(entry)
+        File.directory?(File.join(stale_webpack_config_dir, entry))
+      rescue Errno::EACCES, Errno::ELOOP, Errno::ENOENT
+        false
+      end
+
+      def warn_dotfiles_in_webpack_dir(webpack_config_relative_dir, dotfiles, removed_entries)
+        removed_entries_message = if removed_entries.any?
+                                    " Removed stale managed files: #{removed_entries.join(', ')}."
+                                  else
+                                    ""
+                                  end
+        say_status :warning,
+                   "Keeping #{webpack_config_relative_dir}; dotfiles present: #{dotfiles.join(', ')}. " \
+                   "Remove them manually if you want the directory cleaned up." \
+                   "#{removed_entries_message}",
+                   :yellow
+      end
+
+      def non_removable_webpack_entries(all_entries)
+        all_entries.select do |entry|
+          entry.start_with?(".") || !removable_webpack_entry?(entry)
+        end
+      end
+
+      def removable_webpack_entries(all_entries)
+        all_entries.select { |entry| removable_webpack_entry?(entry) }
+      end
+
+      def remove_stale_webpack_files(webpack_config_relative_dir, entries)
+        entries.each_with_object([]) do |entry, removed_entries|
+          relative_path = File.join(webpack_config_relative_dir, entry)
+          full_path = File.join(destination_root, relative_path)
+          remove_file(relative_path, verbose: false)
+          removed_entries << entry unless File.exist?(full_path)
+        rescue Errno::EACCES, Errno::ELOOP, Errno::ENOENT, Errno::ENOTDIR
+          # If we cannot stat after removal attempt, conservatively report as not removed.
+          nil
+        end
+      end
+
+      def removable_webpack_entry?(entry)
+        return false unless REMOVABLE_WEBPACK_FILES.include?(entry)
+
+        full_path = File.join(stale_webpack_config_dir, entry)
+        return false if File.symlink?(full_path)
+        return false unless File.file?(full_path)
+
+        content = safe_read_cleanup_file(full_path)
+        return false unless content
+
+        return removable_webpack_main_config?(content) if entry == "webpack.config.js"
+
+        removable_managed_webpack_entry?(entry, content)
+      rescue Errno::EACCES, Errno::ELOOP, Errno::ENOENT, Errno::ENOTDIR
+        false
+      end
+
+      def removable_webpack_main_config?(content)
+        webpack_template = rendered_template_for_cleanup("base/base/config/webpack/webpack.config.js.tt")
+        return standard_shakapacker_config?(content) if webpack_template.equal?(TEMPLATE_RENDER_FAILED)
+
+        # Cleanup is deliberately comment-sensitive (unlike copy_webpack_main_config)
+        # so comment-only edits keep the file as a potential customization.
+        standard_shakapacker_config?(content) || content_matches_template?(content, webpack_template)
+      end
+
+      def removable_managed_webpack_entry?(entry, content)
+        template_path = MANAGED_WEBPACK_FILE_TEMPLATES[entry]
+        return false unless template_path
+
+        rendered_template = rendered_template_for_cleanup(template_path)
+        return false if rendered_template.equal?(TEMPLATE_RENDER_FAILED)
+
+        content_matches_template?(content, rendered_template)
+      end
+
+      def rendered_template_for_cleanup(template_path)
+        @rendered_template_cache ||= {}
+        @rendered_template_cache[template_path] ||= begin
+          # Cleanup comparisons only need the injected documentation comment.
+          template_doc_config = { message: DOCS_REFERENCE_MESSAGE }
+          template_content = File.read(File.join(self.class.source_root, template_path))
+          # Render against current generator options. Any mismatch is treated as non-removable,
+          # which is intentional because cleanup should be conservative.
+          # Note: files originally generated with --pro or --rsc will not match when the
+          # current run omits those options; in that case, we preserve the directory.
+          # Templates rely on config[:message] plus a small helper subset exposed by
+          # TemplateRenderContext (add_documentation_reference, use_pro?, use_rsc?,
+          # shakapacker_version_9_or_higher?). Missing method delegates raise
+          # NoMethodError and are caught below, treating the file as non-removable.
+          # Missing config hash keys return nil silently, so any new config key
+          # required by templates must be added to template_doc_config above.
+          # Use TemplateRenderContext#erb_binding to avoid leaking method-local
+          # variables from rendered_template_for_cleanup into the ERB scope.
+          template_render_context = TemplateRenderContext.new(self, template_doc_config)
+          ERB.new(template_content, trim_mode: "-").result(template_render_context.erb_binding)
+        rescue StandardError => e
+          say_status :warning,
+                     "Could not render template #{template_path} for cleanup check (#{e.class}: #{e.message}); " \
+                     "treating as non-removable",
+                     :yellow
+          # Rendering failures should never abort installation. Returning a sentinel
+          # guarantees a non-match so the file is treated as non-removable.
+          # We cache the sentinel intentionally (same options within one generator run)
+          # so repeated checks stay consistent and avoid noisy duplicate warnings.
+          TEMPLATE_RENDER_FAILED
+        end
+      end
+
+      def stale_webpack_config_dir
+        File.join(destination_root, "config/webpack")
+      end
+
+      def stale_webpack_config_entries
+        Dir.children(stale_webpack_config_dir).sort
+      rescue Errno::EACCES, Errno::ENOENT, Errno::ENOTDIR
+        # TOCTOU: directory may disappear between exist? check and read
+        nil
+      end
+
+      def safe_read_cleanup_file(path)
+        File.read(path)
+      rescue Errno::EACCES, Errno::ELOOP, Errno::ENOENT, Errno::EISDIR, Errno::ENOTDIR
+        nil
+      end
+
+      def standard_shakapacker_config?(content, strip_comments: false)
+        # Keep strip_comments false by default so comment-only edits are treated as
+        # potential customizations during cleanup. Callers can pass true when they
+        # need historical comment-insensitive replacement matching.
         # Get the expected default config based on Shakapacker version
         expected_configs = shakapacker_default_configs
 
         # Check if the content matches any of the known default configurations
-        expected_configs.any? { |config| content_matches_template?(content, config) }
+        expected_configs.any? { |config| content_matches_template?(content, config, strip_comments: strip_comments) }
       end
 
-      def content_matches_template?(content, template)
+      def content_matches_template?(content, template, strip_comments: false)
         # Normalize whitespace and compare
-        normalize_config_content(content) == normalize_config_content(template)
+        normalize_config_content(content, strip_comments: strip_comments) ==
+          normalize_config_content(template, strip_comments: strip_comments)
       end
 
-      def normalize_config_content(content)
-        # Remove comments, normalize whitespace, and clean up for comparison
-        content.gsub(%r{//.*$}, "")                    # Remove single-line comments
-               .gsub(%r{/\*.*?\*/}m, "")               # Remove multi-line comments
-               .gsub(/\s+/, " ")                       # Normalize whitespace
-               .strip
+      def normalize_config_content(content, strip_comments: false)
+        normalized_content = content
+        if strip_comments
+          # Replacement detection historically removed inline // comments too.
+          # Note: this also strips `//` in string literals (for example URLs),
+          # which can yield false-negatives and prompt for replacement.
+          normalized_content = normalized_content.gsub(%r{//.*$}, "")
+                                                 .gsub(%r{/\*.*?\*/}m, "")
+        end
+
+        # Normalize whitespace while preserving comments by default so added comments
+        # count as potential customizations and keep cleanup conservative.
+        normalized_content.gsub(/\s+/, " ").strip
       end
 
       def shakapacker_default_configs

data/lib/generators/react_on_rails/generator_messages.rb

@@ -47,11 +47,7 @@ module GeneratorMessages
       package_manager = detect_package_manager
       shakapacker_status = build_shakapacker_status_section(shakapacker_just_installed: shakapacker_just_installed)
       render_example = build_render_example(component_name: component_name, route: route, rsc: rsc)
-      render_label = if rsc
-                       "• Streaming server rendering in app/views/#{route}/index.html.erb:"
-                     else
-                       "• Server-side rendering - Enabled with prerender option in app/views/#{route}/index.html.erb:"
-                     end
+      render_label = build_render_label(route: route, rsc: rsc)
 
       <<~MSG
 
@@ -90,6 +86,18 @@ module GeneratorMessages
       MSG
     end
 
+    # Uses relative lockfile paths resolved against Dir.pwd, so callers must invoke
+    # this while the current working directory is the target Rails app root.
+    def detect_package_manager
+      # Check for lock files to determine package manager
+      return "yarn" if File.exist?("yarn.lock")
+      return "pnpm" if File.exist?("pnpm-lock.yaml")
+      return "bun" if File.exist?("bun.lock") || File.exist?("bun.lockb")
+
+      # Default to npm (Shakapacker 8.x default) - covers package-lock.json and no lockfile
+      "npm"
+    end
+
     private
 
     def build_render_example(component_name:, route:, rsc:)
@@ -100,6 +108,11 @@ module GeneratorMessages
       end
     end
 
+    def build_render_label(route:, rsc:)
+      prefix = rsc ? "Streaming server rendering" : "Server-side rendering - Enabled with prerender option"
+      "• #{prefix} in app/views/#{route}/index.html.erb:"
+    end
+
     def build_process_manager_section
       process_manager = detect_process_manager
       if process_manager
@@ -196,17 +209,5 @@ module GeneratorMessages
       # If version detection fails, don't show a warning to avoid noise
       ""
     end
-
-    def detect_package_manager
-      # Check for lock files to determine package manager
-      if File.exist?("yarn.lock")
-        "yarn"
-      elsif File.exist?("pnpm-lock.yaml")
-        "pnpm"
-      else
-        # Default to npm (Shakapacker 8.x default) - covers package-lock.json and no lockfile
-        "npm"
-      end
-    end
   end
 end

data/lib/generators/react_on_rails/install_generator.rb

@@ -8,6 +8,8 @@ require_relative "generator_messages"
 require_relative "js_dependency_manager"
 require_relative "pro_setup"
 require_relative "rsc_setup"
+# Load-path require: git_utils lives under react_on_rails/lib, not relative to this generator directory.
+require "react_on_rails/git_utils"
 
 module ReactOnRails
   module Generators
@@ -100,9 +102,7 @@ module ReactOnRails
         if installation_prerequisites_met? || options.ignore_warnings?
           invoke_generators
           add_bin_scripts
-          # Only add the post install message if not using Redux
-          # Redux generator handles its own messages
-          add_post_install_message unless options.redux?
+          add_post_install_message
         else
           error = <<~MSG.strip
             🚫 React on Rails generator prerequisites not met!
@@ -148,6 +148,7 @@ module ReactOnRails
         # - Without --rsc: Normal behavior (HelloWorld or HelloWorldApp based on --redux)
         if options.redux?
           invoke "react_on_rails:react_with_redux", [], { typescript: options.typescript?,
+                                                          invoked_by_install: true,
                                                           force: options[:force], skip: options[:skip],
                                                           pretend: options[:pretend] }
         elsif !use_rsc?
@@ -242,6 +243,7 @@ module ReactOnRails
       end
 
       def ensure_shakapacker_installed
+        @shakapacker_setup_incomplete = false
         return if shakapacker_configured?
 
         if options[:pretend]
@@ -250,14 +252,19 @@ module ReactOnRails
         end
 
         print_shakapacker_setup_banner
-        ensure_shakapacker_in_gemfile
+        gemfile_ok = ensure_shakapacker_in_gemfile
+        @shakapacker_setup_incomplete = true unless gemfile_ok
 
         # NOTE: File.exist?/File.read use Dir.pwd (not destination_root) because
         # Rails generators always run from the destination root. This is consistent
         # with other relative-path file checks in this generator (e.g. shakapacker_configured?).
         yml_content_before = File.exist?(SHAKAPACKER_YML_PATH) ? File.read(SHAKAPACKER_YML_PATH) : nil
 
-        finalize_shakapacker_setup(yml_content_before) if install_shakapacker
+        if install_shakapacker
+          finalize_shakapacker_setup(yml_content_before)
+        else
+          @shakapacker_setup_incomplete = true
+        end
       end
 
       # Checks whether "shakapacker" is explicitly declared in this project's Gemfile.
@@ -297,6 +304,11 @@ module ReactOnRails
       end
 
       def add_post_install_message
+        if shakapacker_setup_incomplete?
+          GeneratorMessages.add_warning(incomplete_installation_message)
+          return
+        end
+
         # Determine what route and component will be created by the generator
         if use_rsc? && !options.redux?
           # RSC without Redux: HelloServer replaces HelloWorld
@@ -315,6 +327,67 @@ module ReactOnRails
                                    ))
       end
 
+      def shakapacker_setup_incomplete?
+        # Strict comparison keeps nil (unset) distinct from true.
+        @shakapacker_setup_incomplete == true
+      end
+
+      def recovery_install_command
+        flags = []
+        flags << "--redux" if options.redux?
+        flags << "--typescript" if options.typescript?
+        flags << "--rspack" if options.rspack?
+
+        if use_rsc?
+          flags << "--rsc"
+        elsif options.pro?
+          flags << "--pro"
+        end
+
+        ["rails generate react_on_rails:install", *flags].join(" ")
+      end
+
+      def recovery_working_tree_lines
+        [
+          "If this run created or changed files, clean up your working tree before rerunning",
+          "(commit, stash, or discard the partial changes), or re-run with --ignore-warnings",
+          "if you intentionally want to continue on a dirty tree."
+        ]
+      end
+
+      def recovery_working_tree_note
+        "#{recovery_working_tree_lines.join("\n")}\n"
+      end
+
+      def recovery_working_tree_step(step_number)
+        first_line, *remaining_lines = recovery_working_tree_lines
+        (["#{step_number}. #{first_line}"] + remaining_lines.map { |line| "   #{line}" }).join("\n")
+      end
+
+      def incomplete_installation_message
+        package_install_step = "#{GeneratorMessages.detect_package_manager} install"
+
+        <<~MSG
+
+          ⚠️  React on Rails installation is incomplete.
+          ─────────────────────────────────────────────────────────────────────────
+          Shakapacker setup failed, so this app is not ready to run yet.
+          Avoid running ./bin/dev until Shakapacker is installed successfully.
+          Note: Some generator files may have been partially created during this run.
+
+          Next steps:
+          1. #{Rainbow('bundle install').cyan}
+          2. #{Rainbow('bundle exec rails shakapacker:install').cyan}
+          3. #{Rainbow(package_install_step).cyan}
+          #{recovery_working_tree_step(4)}
+          5. Re-run #{Rainbow(recovery_install_command).cyan}
+             (add #{Rainbow('--force').cyan} to overwrite files if needed)
+
+          Troubleshooting:
+          • https://github.com/shakacode/shakapacker/blob/main/docs/installation.md
+        MSG
+      end
+
       def shakapacker_loaded_in_process?(gem_name)
         Gem.loaded_specs.key?(gem_name)
       end
@@ -366,15 +439,16 @@ module ReactOnRails
       end
 
       def ensure_shakapacker_in_gemfile
-        return if shakapacker_in_gemfile?
+        return true if shakapacker_in_gemfile?
 
         say "📝 Adding Shakapacker to Gemfile...", :yellow
         # Use with_unbundled_env to prevent inheriting BUNDLE_GEMFILE from parent process
         # See: https://github.com/shakacode/react_on_rails/issues/2287
         success = Bundler.with_unbundled_env { system("bundle add shakapacker --strict") }
-        return if success
+        return true if success
 
         handle_shakapacker_gemfile_error
+        false
       end
 
       def install_shakapacker
@@ -443,7 +517,8 @@ module ReactOnRails
           Please try manually:
               bundle add shakapacker --strict
 
-          Then re-run: rails generate react_on_rails:install
+          #{recovery_working_tree_note}
+          Then re-run: #{recovery_install_command}
         MSG
         GeneratorMessages.add_error(error)
         raise Thor::Error, error unless options.ignore_warnings?
@@ -464,7 +539,8 @@ module ReactOnRails
           2. Run: bundle install
           3. Try manually: bundle exec rails shakapacker:install
           4. Check for error output above
-          5. Re-run: rails generate react_on_rails:install
+          #{recovery_working_tree_step(5)}
+          6. Re-run: #{recovery_install_command}
 
           Need help? Visit: https://github.com/shakacode/shakapacker/blob/main/docs/installation.md
         MSG

data/lib/generators/react_on_rails/react_with_redux_generator.rb

@@ -18,6 +18,11 @@ module ReactOnRails
                    desc: "Generate TypeScript files",
                    aliases: "-T"
 
+      class_option :invoked_by_install,
+                   type: :boolean,
+                   default: false,
+                   hide: true
+
       def create_redux_directories
         # Create auto-bundling directory structure for Redux
         empty_directory("app/javascript/src/HelloWorldApp/ror_components")
@@ -90,6 +95,8 @@ module ReactOnRails
       end
 
       def add_redux_specific_messages
+        return if options.invoked_by_install?
+
         # Append Redux-specific post-install instructions
         GeneratorMessages.add_info(
           GeneratorMessages.helpful_message_after_installation(component_name: "HelloWorldApp", route: "hello_world")