docs: simplify server_bundle_output_path configuration documentation

- Focus on key message that default will change to "ssr-generated"
- Note that warning will be shown if left as nil
- Remove unnecessary implementation details about fallback order
- Simplify enforcement requirements

Co-authored-by: Justin Gordon <[email protected]>

Author: github-actions[bot]

CHANGELOG.md

@@ -51,6 +51,11 @@ Changes since the last non-beta release.
 
 - **Non-Packer Environment Compatibility**: Fixed potential NoMethodError when using bundle path resolution in environments without Shakapacker
 - **Server Bundle Detection**: Improved server bundle detection to work correctly with both `server_bundle_js_file` and `rsc_bundle_js_file` configurations
+- **Shakapacker version requirements**: Fixed inconsistent version requirements between basic pack generation (6.5.1+) and advanced auto-bundling features (7.0.0+). Added backward compatibility for users on Shakapacker 6.5.1-6.9.x while providing clear upgrade guidance for advanced features. Added new constants `MINIMUM_SHAKAPACKER_VERSION_FOR_AUTO_BUNDLING` and improved version checking performance with caching. [PR 1798](https://github.com/shakacode/react_on_rails/pull/1798)
+
+#### Code Cleanup
+
+- **PackerUtils abstraction removal**: Removed unnecessary `PackerUtils.packer` abstraction method and replaced all calls with direct `::Shakapacker` usage. This simplifies the codebase by eliminating an abstraction layer that was originally created to support multiple webpack tools but is no longer needed since we only support Shakapacker. All tests updated accordingly. [PR 1798](https://github.com/shakacode/react_on_rails/pull/1798) by [claude-code](https://claude.ai/code)
 
 ### [16.0.1-rc.2] - 2025-09-20
 

lib/generators/react_on_rails/base_generator.rb

@@ -24,7 +24,7 @@ def add_hello_world_route
       end
 
       def create_react_directories
-        # Create auto-registration directory structure for non-Redux components only
+        # Create auto-bundling directory structure for non-Redux components only
         # Redux components handle their own directory structure
         return if options.redux?
 

lib/generators/react_on_rails/react_with_redux_generator.rb

@@ -19,7 +19,7 @@ class ReactWithReduxGenerator < Rails::Generators::Base
                    aliases: "-T"
 
       def create_redux_directories
-        # Create auto-registration directory structure for Redux
+        # Create auto-bundling directory structure for Redux
         empty_directory("app/javascript/src/HelloWorldApp/ror_components")
 
         # Create Redux support directories within the component directory
@@ -31,7 +31,7 @@ def copy_base_files
         base_js_path = "redux/base"
         ext = component_extension(options)
 
-        # Copy Redux-connected component to auto-registration structure
+        # Copy Redux-connected component to auto-bundling structure
         copy_file("#{base_js_path}/app/javascript/bundles/HelloWorld/startup/HelloWorldApp.client.#{ext}",
                   "app/javascript/src/HelloWorldApp/ror_components/HelloWorldApp.client.#{ext}")
         copy_file("#{base_js_path}/app/javascript/bundles/HelloWorld/startup/HelloWorldApp.server.#{ext}",

lib/react_on_rails/configuration.rb

@@ -186,7 +186,7 @@ def validate_generated_component_packs_loading_strategy
         1. Use :sync or :defer loading strategy instead of :async
         2. Upgrade to Shakapacker v8.2.0 or above to enable async script loading
       MSG
-      if PackerUtils.shakapacker_version_requirement_met?("8.2.0")
+      if ReactOnRails::PackerUtils.shakapacker_version_requirement_met?("8.2.0")
         self.generated_component_packs_loading_strategy ||= :async
       elsif generated_component_packs_loading_strategy.nil?
         Rails.logger.warn("**WARNING** #{msg}")
@@ -228,11 +228,8 @@ def check_autobundling_requirements
       raise_missing_components_subdirectory if auto_load_bundle && !components_subdirectory.present?
       return unless components_subdirectory.present?
 
-      ReactOnRails::PackerUtils.raise_shakapacker_not_installed unless ReactOnRails::PackerUtils.using_packer?
       ReactOnRails::PackerUtils.raise_shakapacker_version_incompatible_for_autobundling unless
-        ReactOnRails::PackerUtils.shakapacker_version_requirement_met?(
-          ReactOnRails::PacksGenerator::MINIMUM_SHAKAPACKER_VERSION
-        )
+        ReactOnRails::PackerUtils.supports_autobundling?
       ReactOnRails::PackerUtils.raise_nested_entries_disabled unless ReactOnRails::PackerUtils.nested_entries?
     end
 
@@ -267,8 +264,6 @@ def adjust_precompile_task
     end
 
     def error_if_using_packer_and_generated_assets_dir_not_match_public_output_path
-      return unless ReactOnRails::PackerUtils.using_packer?
-
       return if generated_assets_dir.blank?
 
       packer_public_output_path = ReactOnRails::PackerUtils.packer_public_output_path
@@ -302,7 +297,7 @@ def check_server_render_method_is_only_execjs
     end
 
     def ensure_generated_assets_dir_present
-      return if generated_assets_dir.present? || ReactOnRails::PackerUtils.using_packer?
+      return if generated_assets_dir.present?
 
       self.generated_assets_dir = DEFAULT_GENERATED_ASSETS_DIR
       Rails.logger.warn "ReactOnRails: Set generated_assets_dir to default: #{DEFAULT_GENERATED_ASSETS_DIR}"
@@ -311,20 +306,13 @@ def ensure_generated_assets_dir_present
     def configure_generated_assets_dirs_deprecation
       return if generated_assets_dirs.blank?
 
-      if ReactOnRails::PackerUtils.using_packer?
-        packer_public_output_path = ReactOnRails::PackerUtils.packer_public_output_path
-        # rubocop:disable Layout/LineLength
-        packer_name = "Shakapacker"
-
-        Rails.logger.warn "Error configuring config/initializers/react_on_rails. Define neither the generated_assets_dirs nor " \
-                          "the generated_assets_dir when using #{packer_name}. This is defined by " \
-                          "public_output_path specified in shakapacker.yml = #{packer_public_output_path}."
-        # rubocop:enable Layout/LineLength
-        return
-      end
-
-      Rails.logger.warn "[DEPRECATION] ReactOnRails: Use config.generated_assets_dir rather than " \
-                        "generated_assets_dirs"
+      # With Shakapacker always available:
+      packer_public_output_path = ReactOnRails::PackerUtils.packer_public_output_path
+      # rubocop:disable Layout/LineLength
+      Rails.logger.warn "Error configuring config/initializers/react_on_rails. Define neither the generated_assets_dirs nor " \
+                        "the generated_assets_dir when using Shakapacker. This is defined by " \
+                        "public_output_path specified in shakapacker.yml = #{packer_public_output_path}."
+      # rubocop:enable Layout/LineLength
       if generated_assets_dir.blank?
         self.generated_assets_dir = generated_assets_dirs
       else

lib/react_on_rails/packer_utils.rb

@@ -2,33 +2,16 @@
 
 module ReactOnRails
   module PackerUtils
-    def self.using_packer?
-      return @using_packer if defined?(@using_packer)
-
-      # Shakapacker is required by gemspec, but tests may mock gem_available? to return false
-      @using_packer = ReactOnRails::Utils.gem_available?("shakapacker")
-    end
-
-    def self.packer
-      return nil unless using_packer?
-
-      require "shakapacker"
-      ::Shakapacker
-    end
-
     def self.dev_server_running?
-      return false unless using_packer?
-
-      packer.dev_server.running?
+      Shakapacker.dev_server.running?
     end
 
     def self.dev_server_url
-      "#{packer.dev_server.protocol}://#{packer.dev_server.host_with_port}"
+      "#{Shakapacker.dev_server.protocol}://#{Shakapacker.dev_server.host_with_port}"
     end
 
     def self.shakapacker_version
       return @shakapacker_version if defined?(@shakapacker_version)
-      return nil unless ReactOnRails::Utils.gem_available?("shakapacker")
 
       @shakapacker_version = Gem.loaded_specs["shakapacker"].version.to_s
     end
@@ -46,11 +29,15 @@ def self.shakapacker_version_requirement_met?(required_version)
       Gem::Version.new(shakapacker_version) >= Gem::Version.new(required_version)
     end
 
+    def self.supports_autobundling?
+      shakapacker_version_requirement_met?(ReactOnRails::PacksGenerator::MINIMUM_SHAKAPACKER_VERSION)
+    end
+
     # This returns either a URL for the webpack-dev-server, non-server bundle or
     # the hashed server bundle if using the same bundle for the client.
     # Otherwise returns a file path.
     def self.bundle_js_uri_from_packer(bundle_name)
-      hashed_bundle_name = packer.manifest.lookup!(bundle_name)
+      hashed_bundle_name = Shakapacker.manifest.lookup!(bundle_name)
 
       # Support for hashing the server-bundle and having that built
       # the webpack-dev-server is provided by the config value
@@ -59,7 +46,7 @@ def self.bundle_js_uri_from_packer(bundle_name)
       is_bundle_running_on_server = (bundle_name == ReactOnRails.configuration.server_bundle_js_file) ||
                                     (bundle_name == ReactOnRails.configuration.rsc_bundle_js_file)
 
-      if packer.dev_server.running? && (!is_bundle_running_on_server ||
+      if Shakapacker.dev_server.running? && (!is_bundle_running_on_server ||
         ReactOnRails.configuration.same_bundle_for_client_and_server)
         "#{dev_server_url}#{hashed_bundle_name}"
       else
@@ -68,7 +55,7 @@ def self.bundle_js_uri_from_packer(bundle_name)
     end
 
     def self.public_output_uri_path
-      "#{packer.config.public_output_path.relative_path_from(packer.config.public_path)}/"
+      "#{Shakapacker.config.public_output_path.relative_path_from(Shakapacker.config.public_path)}/"
     end
 
     # The function doesn't ensure that the asset exists.
@@ -83,35 +70,35 @@ def self.asset_uri_from_packer(asset_name)
     end
 
     def self.precompile?
-      using_packer? ? ::Shakapacker.config.shakapacker_precompile? : false
+      ::Shakapacker.config.shakapacker_precompile?
     end
 
     def self.packer_source_path
-      packer.config.source_path
+      Shakapacker.config.source_path
     end
 
     def self.packer_source_entry_path
-      packer.config.source_entry_path
+      Shakapacker.config.source_entry_path
     end
 
     def self.nested_entries?
-      packer.config.nested_entries?
+      Shakapacker.config.nested_entries?
     end
 
     def self.packer_public_output_path
-      packer.config.public_output_path.to_s
+      Shakapacker.config.public_output_path.to_s
     end
 
     def self.manifest_exists?
-      packer.config.public_manifest_path.exist?
+      Shakapacker.config.public_manifest_path.exist?
     end
 
     def self.packer_source_path_explicit?
-      packer.config.send(:data)[:source_path].present?
+      Shakapacker.config.send(:data)[:source_path].present?
     end
 
     def self.check_manifest_not_cached
-      return unless using_packer? && packer.config.cache_manifest?
+      return unless Shakapacker.config.cache_manifest?
 
       msg = <<-MSG.strip_heredoc
           ERROR: you have enabled cache_manifest in the #{Rails.env} env when using the
@@ -153,15 +140,5 @@ def self.raise_shakapacker_version_incompatible_for_autobundling
 
       raise ReactOnRails::Error, msg
     end
-
-    def self.raise_shakapacker_not_installed
-      msg = <<~MSG
-        **ERROR** ReactOnRails: Missing Shakapacker gem. Please upgrade to use Shakapacker \
-        #{ReactOnRails::PacksGenerator::MINIMUM_SHAKAPACKER_VERSION} or above to use the \
-        automated bundle generation feature.
-      MSG
-
-      raise ReactOnRails::Error, msg
-    end
   end
 end

lib/react_on_rails/system_checker.rb

@@ -618,14 +618,10 @@ def report_shakapacker_version_with_threshold
           version = shakapacker_match[1].strip
 
           begin
-            # Use proper semantic version comparison
-            version_obj = Gem::Version.new(version)
-            threshold_version = Gem::Version.new("8.2")
-
-            if version_obj >= threshold_version
-              add_success("✅ Shakapacker #{version} (supports React on Rails auto-registration)")
+            if ReactOnRails::PackerUtils.supports_autobundling?
+              add_success("✅ Shakapacker #{version} (supports React on Rails auto-bundling)")
             else
-              add_warning("⚠️  Shakapacker #{version} - Version 8.2+ needed for React on Rails auto-registration")
+              add_warning("⚠️  Shakapacker #{version} - Version 8.2+ needed for React on Rails auto-bundling")
             end
           rescue ArgumentError
             # Fallback for invalid version strings

lib/react_on_rails/test_helper.rb

@@ -86,8 +86,7 @@ def self.ensure_assets_compiled(webpack_assets_status_checker: nil,
           puts
           @printed_once = true
 
-          if ReactOnRails::PackerUtils.using_packer? &&
-             ReactOnRails::Utils.using_packer_source_path_is_not_defined_and_custom_node_modules?
+          if ReactOnRails::Utils.using_packer_source_path_is_not_defined_and_custom_node_modules?
             msg = <<-MSG.strip_heredoc
               WARNING: Define config/shakapacker.yml to include sourcePath to configure
               the location of your JavaScript source for React on Rails.

lib/react_on_rails/test_helper/webpack_assets_status_checker.rb

@@ -31,8 +31,7 @@ def stale_generated_webpack_files
       end
 
       def stale_generated_files(files)
-        manifest_needed = ReactOnRails::PackerUtils.using_packer? &&
-                          !ReactOnRails::PackerUtils.manifest_exists?
+        manifest_needed = !ReactOnRails::PackerUtils.manifest_exists?
 
         return ["manifest.json"] if manifest_needed
 

lib/react_on_rails/utils.rb

@@ -91,17 +91,17 @@ def self.bundle_js_file_path(bundle_name)
       #    a. The webpack manifest plugin would have a race condition where the same manifest.json
       #       is edited by both the webpack-dev-server
       #    b. There is no good reason to hash the server bundle name.
-      if ReactOnRails::PackerUtils.using_packer? && bundle_name != "manifest.json"
+      if bundle_name == "manifest.json"
+        # Default to the non-hashed name in the specified output directory, which, for legacy
+        # React on Rails, this is the output directory picked up by the asset pipeline.
+        # For Shakapacker, this is the public output path defined in the (shaka/web)packer.yml file.
+        File.join(generated_assets_full_path, bundle_name)
+      else
         begin
           ReactOnRails::PackerUtils.bundle_js_uri_from_packer(bundle_name)
         rescue Shakapacker::Manifest::MissingEntryError
           handle_missing_manifest_entry(bundle_name)
         end
-      else
-        # Default to the non-hashed name in the specified output directory, which, for legacy
-        # React on Rails, this is the output directory picked up by the asset pipeline.
-        # For Shakapacker, this is the public output path defined in the (shaka/web)packer.yml file.
-        File.join(generated_assets_full_path, bundle_name)
       end
     end
 
@@ -113,10 +113,8 @@ def self.bundle_js_file_path(bundle_name)
       # Build fallback locations conditionally based on packer availability
       fallback_locations = []
 
-      # 1. Environment-specific path (e.g., public/webpack/test) - only if using packer
-      if ReactOnRails::PackerUtils.using_packer?
-        fallback_locations << File.join(ReactOnRails::PackerUtils.packer_public_output_path, bundle_name)
-      end
+      # 1. Environment-specific path (e.g., public/webpack/test)
+      fallback_locations << File.join(ReactOnRails::PackerUtils.packer_public_output_path, bundle_name)
 
       # 2. Standard Shakapacker location (public/packs)
       fallback_locations << File.join("public", "packs", bundle_name)
@@ -171,11 +169,7 @@ def self.react_client_manifest_file_path
       return @react_client_manifest_path if @react_client_manifest_path && !Rails.env.development?
 
       file_name = ReactOnRails.configuration.react_client_manifest_file
-      @react_client_manifest_path = if ReactOnRails::PackerUtils.using_packer?
-                                      ReactOnRails::PackerUtils.asset_uri_from_packer(file_name)
-                                    else
-                                      File.join(generated_assets_full_path, file_name)
-                                    end
+      @react_client_manifest_path = ReactOnRails::PackerUtils.asset_uri_from_packer(file_name)
     end
 
     # React Server Manifest is generated by the server bundle.
@@ -217,26 +211,16 @@ def self.prepend_cd_node_modules_directory(cmd)
     end
 
     def self.source_path
-      if ReactOnRails::PackerUtils.using_packer?
-        ReactOnRails::PackerUtils.packer_source_path
-      else
-        ReactOnRails.configuration.node_modules_location
-      end
+      ReactOnRails::PackerUtils.packer_source_path
     end
 
     def self.using_packer_source_path_is_not_defined_and_custom_node_modules?
-      return false unless ReactOnRails::PackerUtils.using_packer?
-
       !ReactOnRails::PackerUtils.packer_source_path_explicit? &&
         ReactOnRails.configuration.node_modules_location.present?
     end
 
     def self.public_bundles_full_path
-      if ReactOnRails::PackerUtils.using_packer?
-        ReactOnRails::PackerUtils.packer_public_output_path
-      else
-        File.expand_path(ReactOnRails.configuration.generated_assets_dir)
-      end
+      ReactOnRails::PackerUtils.packer_public_output_path
     end
 
     # DEPRECATED: Use public_bundles_full_path for clarity about public vs private bundle paths