Add configurable loading strategy for generated component packs

- Replace `defer_generated_component_packs` with more flexible `generated_component_packs_loading_strategy`
- Add support for `:async`, `:defer`, and `:sync` loading strategies
- Validate loading strategy based on Shakapacker version
- Update helper to support new loading strategy configuration
- Add comprehensive specs for the new configuration option

Author: AbanoubGhadban

lib/react_on_rails/configuration.rb

@@ -43,13 +43,13 @@ def self.configuration
       i18n_output_format: nil,
       components_subdirectory: nil,
       make_generated_server_bundle_the_entrypoint: false,
-      defer_generated_component_packs: false,
       # forces the loading of React components
       force_load: true,
       # Maximum time in milliseconds to wait for client-side component registration after page load.
       # If exceeded, an error will be thrown for server-side rendered components not registered on the client.
       # Set to 0 to disable the timeout and wait indefinitely for component registration.
-      component_registry_timeout: DEFAULT_COMPONENT_REGISTRY_TIMEOUT
+      component_registry_timeout: DEFAULT_COMPONENT_REGISTRY_TIMEOUT,
+      generated_component_packs_loading_strategy: nil
     )
   end
 
@@ -64,7 +64,7 @@ class Configuration
                   :server_render_method, :random_dom_id, :auto_load_bundle,
                   :same_bundle_for_client_and_server, :rendering_props_extension,
                   :make_generated_server_bundle_the_entrypoint,
-                  :defer_generated_component_packs, :force_load, :rsc_bundle_js_file,
+                  :generated_component_packs_loading_strategy, :force_load, :rsc_bundle_js_file,
                   :react_client_manifest_file, :component_registry_timeout
 
     # rubocop:disable Metrics/AbcSize
@@ -76,7 +76,7 @@ def initialize(node_modules_location: nil, server_bundle_js_file: nil, prerender
                    skip_display_none: nil, generated_assets_dirs: nil,
                    generated_assets_dir: nil, webpack_generated_files: nil,
                    rendering_extension: nil, build_test_command: nil,
-                   build_production_command: nil, defer_generated_component_packs: nil,
+                   build_production_command: nil, generated_component_packs_loading_strategy: nil,
                    same_bundle_for_client_and_server: nil,
                    i18n_dir: nil, i18n_yml_dir: nil, i18n_output_format: nil, i18n_yml_safe_load_options: nil,
                    random_dom_id: nil, server_render_method: nil, rendering_props_extension: nil,
@@ -122,8 +122,8 @@ def initialize(node_modules_location: nil, server_bundle_js_file: nil, prerender
       self.components_subdirectory = components_subdirectory
       self.auto_load_bundle = auto_load_bundle
       self.make_generated_server_bundle_the_entrypoint = make_generated_server_bundle_the_entrypoint
-      self.defer_generated_component_packs = defer_generated_component_packs
       self.force_load = force_load
+      self.generated_component_packs_loading_strategy = generated_component_packs_loading_strategy
     end
     # rubocop:enable Metrics/AbcSize
 
@@ -139,6 +139,7 @@ def setup_config_values
       # check_deprecated_settings
       adjust_precompile_task
       check_component_registry_timeout
+      validate_generated_component_packs_loading_strategy
     end
 
     private
@@ -151,6 +152,32 @@ def check_component_registry_timeout
       raise ReactOnRails::Error, "component_registry_timeout must be a positive integer"
     end
 
+    def validate_generated_component_packs_loading_strategy
+      if PackerUtils.shakapacker_version_requirement_met?([8, 2, 0])
+        self.generated_component_packs_loading_strategy ||= :async
+      elsif generated_component_packs_loading_strategy.nil?
+        msg = <<~MSG
+          **WARNING** ReactOnRails: Your current version of #{ReactOnRails::PackerUtils.packer_type.upcase_first} \
+          does not support async script loading which may cause performance issues. Please upgrade to Shakapacker v8.2.0 \
+          or above to enable async script loading for better performance.
+        MSG
+        Rails.logger.warn(msg)
+        self.generated_component_packs_loading_strategy = :sync
+      elsif generated_component_packs_loading_strategy == :async
+        msg = <<~MSG
+          **ERROR** ReactOnRails: Your current version of #{ReactOnRails::PackerUtils.packer_type.upcase_first} \
+          does not support async script loading. Please either:
+          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
+        raise ReactOnRails::Error, msg
+      end
+
+      return if [:async, :defer, :sync].include?(generated_component_packs_loading_strategy)
+
+      raise ReactOnRails::Error, "generated_component_packs_loading_strategy must be either :async, :defer, or :sync"
+    end
+
     def check_autobundling_requirements
       raise_missing_components_subdirectory if auto_load_bundle && !components_subdirectory.present?
       return unless components_subdirectory.present?

lib/react_on_rails/helper.rb

@@ -422,8 +422,15 @@ def load_pack_for_generated_component(react_component_name, render_options)
         is_component_pack_present = File.exist?(generated_components_pack_path(react_component_name))
         raise_missing_autoloaded_bundle(react_component_name) unless is_component_pack_present
       end
-      append_javascript_pack_tag("generated/#{react_component_name}",
-                                 defer: ReactOnRails.configuration.defer_generated_component_packs)
+
+      options = { defer: ReactOnRails.configuration.generated_component_packs_loading_strategy == :defer }
+      # Old versions of Shakapacker don't support async script tags.
+      # ReactOnRails.configure already validates if async loading is supported by the installed Shakapacker version.
+      # Therefore, we only need to pass the async option if the loading strategy is explicitly set to :async
+      if ReactOnRails.configuration.generated_component_packs_loading_strategy == :async
+        options[:async] = true
+      end
+      append_javascript_pack_tag("generated/#{react_component_name}", **options)
       append_stylesheet_pack_tag("generated/#{react_component_name}")
     end
 

spec/dummy/spec/helpers/react_on_rails_helper_spec.rb

@@ -54,6 +54,45 @@ class PlainReactOnRailsHelper
       expect(helper).to have_received(:append_stylesheet_pack_tag).with("generated/component_name")
     end
 
+    context "when async loading is enabled" do
+      before do
+        allow(ReactOnRails.configuration).to receive(:generated_component_packs_loading_strategy).and_return(:async)
+      end
+
+      it "appends the async attribute to the script tag" do
+        original_append_javascript_pack_tag = helper.method(:append_javascript_pack_tag)
+        begin
+          # Temporarily redefine append_javascript_pack_tag to handle the async keyword argument.
+          # This is needed because older versions of Shakapacker (which may be used during testing) don't support async loading,
+          # but we still want to test that the async option is passed correctly when enabled.
+          def helper.append_javascript_pack_tag(name, **options)
+            original_append_javascript_pack_tag.call(name, **options)
+          end
+          allow(helper).to receive(:append_javascript_pack_tag)
+          allow(helper).to receive(:append_stylesheet_pack_tag)
+          expect { helper.load_pack_for_generated_component("component_name", render_options) }.not_to raise_error
+          expect(helper).to have_received(:append_javascript_pack_tag).with("generated/component_name", { defer: false, async: true })
+          expect(helper).to have_received(:append_stylesheet_pack_tag).with("generated/component_name")
+        ensure
+          helper.define_singleton_method(:append_javascript_pack_tag, original_append_javascript_pack_tag)
+        end
+      end
+    end
+
+    context "when defer loading is enabled" do
+      before do
+        allow(ReactOnRails.configuration).to receive(:generated_component_packs_loading_strategy).and_return(:defer)
+      end
+
+      it "appends the defer attribute to the script tag" do
+        allow(helper).to receive(:append_javascript_pack_tag)
+        allow(helper).to receive(:append_stylesheet_pack_tag)
+        expect { helper.load_pack_for_generated_component("component_name", render_options) }.not_to raise_error
+        expect(helper).to have_received(:append_javascript_pack_tag).with("generated/component_name", { defer: true })
+        expect(helper).to have_received(:append_stylesheet_pack_tag).with("generated/component_name")
+      end
+    end
+
     it "throws an error in development if generated component isn't found" do
       allow(Rails.env).to receive(:development?).and_return(true)
       expect { helper.load_pack_for_generated_component("nonexisting_component", render_options) }

spec/react_on_rails/configuration_spec.rb

@@ -265,7 +265,7 @@ module ReactOnRails
       end
 
       expect(ReactOnRails::PackerUtils).to have_received(:using_packer?).thrice
-      expect(ReactOnRails::PackerUtils).to have_received(:shakapacker_version_requirement_met?)
+      expect(ReactOnRails::PackerUtils).to have_received(:shakapacker_version_requirement_met?).twice
       expect(ReactOnRails::PackerUtils).to have_received(:nested_entries?)
     end
 
@@ -277,6 +277,95 @@ module ReactOnRails
 
       expect(ReactOnRails.configuration.random_dom_id).to be(true)
     end
+
+    describe ".generated_component_packs_loading_strategy" do
+      context "when using Shakapacker >= 8.2.0" do
+        before do
+          allow(ReactOnRails::PackerUtils).to receive(:shakapacker_version_requirement_met?)
+            .with([8, 2, 0]).and_return(true)
+        end
+
+        it "defaults to :async" do
+          ReactOnRails.configure {} # rubocop:disable Lint/EmptyBlock
+          expect(ReactOnRails.configuration.generated_component_packs_loading_strategy).to eq(:async)
+        end
+
+        it "accepts :async value" do
+          expect do
+            ReactOnRails.configure do |config|
+              config.generated_component_packs_loading_strategy = :async
+            end
+          end.not_to raise_error
+          expect(ReactOnRails.configuration.generated_component_packs_loading_strategy).to eq(:async)
+        end
+
+        it "accepts :defer value" do
+          expect do
+            ReactOnRails.configure do |config|
+              config.generated_component_packs_loading_strategy = :defer
+            end
+          end.not_to raise_error
+          expect(ReactOnRails.configuration.generated_component_packs_loading_strategy).to eq(:defer)
+        end
+
+        it "accepts :sync value" do
+          expect do
+            ReactOnRails.configure do |config|
+              config.generated_component_packs_loading_strategy = :sync
+            end
+          end.not_to raise_error
+          expect(ReactOnRails.configuration.generated_component_packs_loading_strategy).to eq(:sync)
+        end
+
+        it "raises error for invalid values" do
+          expect do
+            ReactOnRails.configure do |config|
+              config.generated_component_packs_loading_strategy = :invalid
+            end
+          end.to raise_error(ReactOnRails::Error, /must be either :async, :defer, or :sync/)
+        end
+      end
+
+      context "when using Shakapacker < 8.2.0" do
+        before do
+          allow(ReactOnRails::PackerUtils).to receive(:shakapacker_version_requirement_met?)
+            .with([8, 2, 0]).and_return(false)
+          allow(Rails.logger).to receive(:warn)
+        end
+
+        it "defaults to :sync and logs a warning" do
+          ReactOnRails.configure {} # rubocop:disable Lint/EmptyBlock
+          expect(ReactOnRails.configuration.generated_component_packs_loading_strategy).to eq(:sync)
+          expect(Rails.logger).to have_received(:warn).with(/does not support async script loading/)
+        end
+
+        it "accepts :defer value" do
+          expect do
+            ReactOnRails.configure do |config|
+              config.generated_component_packs_loading_strategy = :defer
+            end
+          end.not_to raise_error
+          expect(ReactOnRails.configuration.generated_component_packs_loading_strategy).to eq(:defer)
+        end
+
+        it "accepts :sync value" do
+          expect do
+            ReactOnRails.configure do |config|
+              config.generated_component_packs_loading_strategy = :sync
+            end
+          end.not_to raise_error
+          expect(ReactOnRails.configuration.generated_component_packs_loading_strategy).to eq(:sync)
+        end
+
+        it "raises error for :async value" do
+          expect do
+            ReactOnRails.configure do |config|
+              config.generated_component_packs_loading_strategy = :async
+            end
+          end.to raise_error(ReactOnRails::Error, /does not support async script loading/)
+        end
+      end
+    end
   end
 end