react_on_rails 16.2.0.beta.3 → 16.2.0.beta.8

data/lib/generators/react_on_rails/templates/base/base/config/initializers/react_on_rails.rb.tt

@@ -1,67 +1,47 @@
 # frozen_string_literal: true
 
-# See https://github.com/shakacode/react_on_rails/blob/master/docs/guides/configuration.md
-# for many more options.
+# React on Rails configuration
+# See https://github.com/shakacode/react_on_rails/blob/master/docs/api-reference/configuration.md
+# for complete documentation of all configuration options.
 
 ReactOnRails.configure do |config|
-  # This configures the script to run to build the production assets by webpack. Set this to nil
-  # if you don't want react_on_rails building this file for you.
-  # If nil, then the standard shakacode/shakapacker assets:precompile will run
-  # config.build_production_command = nil
-
-  ################################################################################
   ################################################################################
-  # TEST CONFIGURATION OPTIONS
-  # Below options are used with the use of this test helper:
-  # ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
+  # Server Rendering (Recommended)
   ################################################################################
-
-  # If you are using this in your spec_helper.rb (or rails_helper.rb):
-  #
-  # ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)
-  #
-  # with rspec then this controls what npm command is run
-  # to automatically refresh your webpack assets on every test run.
-  #
-  # Alternately, you can remove the `ReactOnRails::TestHelper.configure_rspec_to_compile_assets`
-  # and set the config/shakapacker.yml option for test to true.
-  config.build_test_command = "RAILS_ENV=test bin/shakapacker"
+  # Configure server bundle for server-side rendering with `prerender: true`
+  # Set to "" if you're not using server rendering
+  config.server_bundle_js_file = "server-bundle.js"
 
   ################################################################################
+  # Test Configuration (Optional)
   ################################################################################
-  # SERVER RENDERING OPTIONS
-  ################################################################################
-  # This is the file used for server rendering of React when using `(prerender: true)`
-  # If you are never using server rendering, you should set this to "".
-  # Note, there is only one server bundle, unlike JavaScript where you want to minimize the size
-  # of the JS sent to the client. For the server rendering, React on Rails creates a pool of
-  # JavaScript execution instances which should handle any component requested.
+  # ⚠️ IMPORTANT: Two mutually exclusive approaches - use ONLY ONE:
   #
-  # While you may configure this to be the same as your client bundle file, this file is typically
-  # different. You should have ONE server bundle which can create all of your server rendered
-  # React components.
+  # RECOMMENDED APPROACH: Set `compile: true` in config/shakapacker.yml test section
+  # - Simpler configuration (no additional setup needed)
+  # - Handled automatically by Shakapacker
   #
-  config.server_bundle_js_file = "server-bundle.js"
-
-  # Configure where server bundles are output. Defaults to "ssr-generated".
-  # This should match your webpack configuration for server bundles.
-  config.server_bundle_output_path = "ssr-generated"
-
-  # Enforce that server bundles are only loaded from private (non-public) directories.
-  # When true, server bundles will only be loaded from the configured server_bundle_output_path.
-  # This is recommended for production to prevent server-side code from being exposed.
-  config.enforce_private_server_bundles = true
+  # ALTERNATIVE APPROACH: Uncomment below AND configure ReactOnRails::TestHelper
+  # - Provides explicit control over test asset compilation timing
+  # - Requires adding ReactOnRails::TestHelper to spec/rails_helper.rb
+  # - See: https://github.com/shakacode/react_on_rails/blob/master/docs/guides/testing-configuration.md
+  #
+  config.build_test_command = "RAILS_ENV=test bin/shakapacker"
 
-  ################################################################################
-  ################################################################################
-  # FILE SYSTEM BASED COMPONENT REGISTRY
-  ################################################################################
-  # `components_subdirectory`  is the name of the matching directories that contain automatically registered components
-  # for use in the Rails views. The default is nil, you can enable the feature by updating it in the next line.
+  config.auto_load_bundle = true
   config.components_subdirectory = "ror_components"
+  ################################################################################
+  # Advanced Configuration
+  ################################################################################
+  # Most configuration options have sensible defaults and don't need to be set.
+  # For advanced options including:
+  # - File-based component registry (components_subdirectory, auto_load_bundle)
+  # - Component loading strategies (async/defer/sync)
+  # - Server bundle security and organization
+  # - I18n configuration
+  # - Server rendering pool configuration
+  # - Custom rendering extensions
+  # - And more...
   #
-  # For automated component registry, `render_component` view helper method tries to load bundle for component from
-  # generated directory. default is false, you can pass option at the time of individual usage or update the default
-  # in the following line
-  config.auto_load_bundle = true
+  # See: https://github.com/shakacode/react_on_rails/blob/master/docs/api-reference/configuration.md
 end

data/lib/generators/react_on_rails/templates/base/base/config/shakapacker.yml

@@ -55,6 +55,11 @@ default: &default
   # https://webpack.js.org/guides/build-performance/#avoid-production-specific-tooling
   useContentHash: false
 
+  # On-demand compilation of packs when modified. Defaults to false.
+  # Set to false if using bin/shakapacker-dev-server or bin/shakapacker --watch via Procfiles.
+  # Set to true only in test environment for on-demand compilation.
+  compile: false
+
   # Setting the asset host here will override Rails.application.config.asset_host.
   # Here, you can set different asset_host per environment. Note that
   # SHAKAPACKER_ASSET_HOST will override both configurations.
@@ -72,7 +77,6 @@ default: &default
 
 development:
   <<: *default
-  compile: true
   compiler_strategy: mtime
 
   # Reference: https://webpack.js.org/configuration/dev-server/

data/lib/react_on_rails/configuration.rb

@@ -41,8 +41,6 @@ module ReactOnRails
       components_subdirectory: nil,
       make_generated_server_bundle_the_entrypoint: false,
       defer_generated_component_packs: false,
-      # React on Rails Pro (licensed) feature - enables immediate hydration of React components
-      immediate_hydration: false,
       # 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.
@@ -64,10 +62,55 @@ module ReactOnRails
                   :server_render_method, :random_dom_id, :auto_load_bundle,
                   :same_bundle_for_client_and_server, :rendering_props_extension,
                   :make_generated_server_bundle_the_entrypoint,
-                  :generated_component_packs_loading_strategy, :immediate_hydration,
+                  :generated_component_packs_loading_strategy,
                   :component_registry_timeout,
                   :server_bundle_output_path, :enforce_private_server_bundles
 
+    # Class instance variable and mutex to track if deprecation warning has been shown
+    # Using mutex to ensure thread-safety in multi-threaded environments
+    @immediate_hydration_warned = false
+    @immediate_hydration_mutex = Mutex.new
+
+    class << self
+      attr_accessor :immediate_hydration_warned, :immediate_hydration_mutex
+    end
+
+    # Deprecated: immediate_hydration configuration has been removed
+    def immediate_hydration=(value)
+      warned = false
+      self.class.immediate_hydration_mutex.synchronize do
+        warned = self.class.immediate_hydration_warned
+        self.class.immediate_hydration_warned = true unless warned
+      end
+
+      return if warned
+
+      Rails.logger.warn <<~WARNING
+        [REACT ON RAILS] The 'config.immediate_hydration' configuration option is deprecated and no longer used.
+        Immediate hydration is now automatically enabled for React on Rails Pro users.
+        Please remove 'config.immediate_hydration = #{value}' from your config/initializers/react_on_rails.rb file.
+        See CHANGELOG.md for migration instructions.
+      WARNING
+    end
+
+    def immediate_hydration
+      warned = false
+      self.class.immediate_hydration_mutex.synchronize do
+        warned = self.class.immediate_hydration_warned
+        self.class.immediate_hydration_warned = true unless warned
+      end
+
+      return nil if warned
+
+      Rails.logger.warn <<~WARNING
+        [REACT ON RAILS] The 'config.immediate_hydration' configuration option is deprecated and no longer used.
+        Immediate hydration is now automatically enabled for React on Rails Pro users.
+        Please remove any references to 'config.immediate_hydration' from your config/initializers/react_on_rails.rb file.
+        See CHANGELOG.md for migration instructions.
+      WARNING
+      nil
+    end
+
     # rubocop:disable Metrics/AbcSize
     def initialize(node_modules_location: nil, server_bundle_js_file: nil, prerender: nil,
                    replay_console: nil, make_generated_server_bundle_the_entrypoint: nil,
@@ -81,7 +124,7 @@ module ReactOnRails
                    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,
-                   components_subdirectory: nil, auto_load_bundle: nil, immediate_hydration: nil,
+                   components_subdirectory: nil, auto_load_bundle: nil,
                    component_registry_timeout: nil, server_bundle_output_path: nil, enforce_private_server_bundles: nil)
       self.node_modules_location = node_modules_location.present? ? node_modules_location : Rails.root
       self.generated_assets_dirs = generated_assets_dirs
@@ -122,7 +165,6 @@ module ReactOnRails
       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.immediate_hydration = immediate_hydration
       self.generated_component_packs_loading_strategy = generated_component_packs_loading_strategy
       self.server_bundle_output_path = server_bundle_output_path
       self.enforce_private_server_bundles = enforce_private_server_bundles
@@ -154,9 +196,9 @@ module ReactOnRails
       raise ReactOnRails::Error, "component_registry_timeout must be a positive integer"
     end
 
-    # rubocop:disable Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
     def validate_generated_component_packs_loading_strategy
-      # rubocop:enable Metrics/CyclomaticComplexity
+      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
       if defer_generated_component_packs
         if %i[async sync].include?(generated_component_packs_loading_strategy)
@@ -176,11 +218,13 @@ module ReactOnRails
         1. Use :defer or :sync loading strategy instead of :async
         2. Upgrade to Shakapacker v8.2.0 or above to enable async script loading
       MSG
-      if generated_component_packs_loading_strategy.nil?
-        # Use defer as the default to ensure generated component packs load and register
-        # components before main bundle executes, avoiding race conditions with async loading
-        self.generated_component_packs_loading_strategy = :defer
-      elsif generated_component_packs_loading_strategy == :async && !PackerUtils.supports_async_loading?
+      if PackerUtils.supports_async_loading?
+        # Default based on Pro license: Pro users get :async, non-Pro users get :defer
+        self.generated_component_packs_loading_strategy ||= (Utils.react_on_rails_pro? ? :async : :defer)
+      elsif generated_component_packs_loading_strategy.nil?
+        Rails.logger.warn("**WARNING** #{msg}")
+        self.generated_component_packs_loading_strategy = :sync
+      elsif generated_component_packs_loading_strategy == :async
         raise ReactOnRails::Error, "**ERROR** #{msg}"
       end
 

data/lib/react_on_rails/controller.rb

@@ -9,13 +9,13 @@ module ReactOnRails
     #             JavaScript code.
     # props: Named parameter props which is a Ruby Hash or JSON string which contains the properties
     #        to pass to the redux store.
-    # immediate_hydration: React on Rails Pro (licensed) feature. Pass as true if you wish to hydrate this
-    #                      store immediately instead of waiting for the page to load.
+    # immediate_hydration: React on Rails Pro (licensed) feature. When nil (default), Pro users get
+    #                      immediate hydration, non-Pro users don't. Can be explicitly overridden.
     #
     # Be sure to include view helper `redux_store_hydration_data` at the end of your layout or view
     # or else there will be no client side hydration of your stores.
     def redux_store(store_name, props: {}, immediate_hydration: nil)
-      immediate_hydration = ReactOnRails.configuration.immediate_hydration if immediate_hydration.nil?
+      immediate_hydration = ReactOnRails::Utils.normalize_immediate_hydration(immediate_hydration, store_name, "Store")
       redux_store_data = { store_name: store_name,
                            props: props,
                            immediate_hydration: immediate_hydration }

data/lib/react_on_rails/dev/server_manager.rb

@@ -144,10 +144,11 @@ module ReactOnRails
           puts help_troubleshooting
         end
 
+        # rubocop:disable Metrics/AbcSize
         def run_from_command_line(args = ARGV)
           require "optparse"
 
-          options = { route: nil, rails_env: nil }
+          options = { route: nil, rails_env: nil, verbose: false }
 
           OptionParser.new do |opts|
             opts.banner = "Usage: dev [command] [options]"
@@ -160,6 +161,10 @@ module ReactOnRails
               options[:rails_env] = env
             end
 
+            opts.on("-v", "--verbose", "Enable verbose output for pack generation") do
+              options[:verbose] = true
+            end
+
             opts.on("-h", "--help", "Prints this help") do
               show_help
               exit
@@ -172,21 +177,23 @@ module ReactOnRails
           # Main execution
           case command
           when "production-assets", "prod"
-            start(:production_like, nil, verbose: false, route: options[:route], rails_env: options[:rails_env])
+            start(:production_like, nil, verbose: options[:verbose], route: options[:route],
+                                         rails_env: options[:rails_env])
           when "static"
-            start(:static, "Procfile.dev-static-assets", verbose: false, route: options[:route])
+            start(:static, "Procfile.dev-static-assets", verbose: options[:verbose], route: options[:route])
           when "kill"
             kill_processes
           when "help", "--help", "-h"
             show_help
           when "hmr", nil
-            start(:development, "Procfile.dev", verbose: false, route: options[:route])
+            start(:development, "Procfile.dev", verbose: options[:verbose], route: options[:route])
           else
             puts "Unknown argument: #{command}"
             puts "Run 'dev help' for usage information"
             exit 1
           end
         end
+        # rubocop:enable Metrics/AbcSize
 
         private
 

data/lib/react_on_rails/doctor.rb

@@ -154,6 +154,7 @@ module ReactOnRails
     def check_configuration_details
       check_shakapacker_configuration_details
       check_react_on_rails_configuration_details
+      check_server_bundle_prerender_consistency
     end
 
     def check_bin_dev_launcher
@@ -166,6 +167,7 @@ module ReactOnRails
 
     def check_testing_setup
       check_rspec_helper_setup
+      check_build_test_configuration
     end
 
     def check_development
@@ -173,6 +175,7 @@ module ReactOnRails
       check_procfile_dev
       check_bin_dev_script
       check_gitignore
+      check_async_usage
     end
 
     def check_javascript_bundles
@@ -732,10 +735,12 @@ module ReactOnRails
       auto_load_match = content.match(/config\.auto_load_bundle\s*=\s*([^\s\n,]+)/)
       checker.add_info("  auto_load_bundle: #{auto_load_match[1]}") if auto_load_match
 
-      # Immediate hydration (Pro feature)
+      # Deprecated immediate_hydration setting
       immediate_hydration_match = content.match(/config\.immediate_hydration\s*=\s*([^\s\n,]+)/)
       if immediate_hydration_match
-        checker.add_info("  immediate_hydration: #{immediate_hydration_match[1]} (React on Rails Pro)")
+        checker.add_warning("  ⚠️  immediate_hydration: #{immediate_hydration_match[1]} (DEPRECATED)")
+        checker.add_info("    💡 This setting is no longer used. Immediate hydration is now automatic for Pro users.")
+        checker.add_info("    💡 Remove this line from your config/initializers/react_on_rails.rb file.")
       end
 
       # Component registry timeout
@@ -1108,6 +1113,124 @@ module ReactOnRails
       end
     end
 
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    def check_server_bundle_prerender_consistency
+      config_path = "config/initializers/react_on_rails.rb"
+      return unless File.exist?(config_path)
+
+      checker.add_info("\n🔍 Server Rendering Consistency:")
+
+      begin
+        content = File.read(config_path)
+
+        # Check for server bundle configuration
+        server_bundle_match = content.match(/config\.server_bundle_js_file\s*=\s*["']([^"']+)["']/)
+        server_bundle_set = server_bundle_match && server_bundle_match[1].present?
+
+        # Check for global prerender setting
+        prerender_match = content.match(/config\.prerender\s*=\s*(true)/)
+        prerender_set = prerender_match
+
+        # Check if prerender is used in views
+        uses_prerender = uses_prerender_in_views?
+
+        # Analyze the configuration
+        if (prerender_set || uses_prerender) && !server_bundle_set
+          checker.add_warning("  ⚠️  Server rendering is enabled but server_bundle_js_file is not configured")
+          checker.add_info("  💡 Set config.server_bundle_js_file = 'server-bundle.js' to enable SSR")
+          checker.add_info("  💡 See: https://www.shakacode.com/react-on-rails/docs/guides/server-rendering")
+        elsif server_bundle_set && !prerender_set && !uses_prerender
+          checker.add_info("  ℹ️  server_bundle_js_file is configured but prerender doesn't appear to be used")
+          checker.add_info("  💡 Either use prerender: true in react_component calls or remove server_bundle_js_file")
+        else
+          checker.add_success("  ✅ Server rendering configuration is consistent")
+        end
+      rescue StandardError => e
+        checker.add_warning("  ⚠️  Could not analyze server rendering configuration: #{e.message}")
+      end
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+    def uses_prerender_in_views?
+      # Check view files for prerender: true
+      view_files = Dir.glob("app/views/**/*.{erb,haml,slim}")
+      view_files.any? do |file|
+        next unless File.exist?(file)
+
+        File.read(file).match?(/prerender:\s*true/)
+      end
+    rescue StandardError
+      false
+    end
+
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength
+    def check_build_test_configuration
+      config_path = "config/initializers/react_on_rails.rb"
+      shakapacker_yml = "config/shakapacker.yml"
+
+      return unless File.exist?(config_path)
+
+      checker.add_info("\n🧪 Test Asset Compilation:")
+
+      begin
+        config_content = File.read(config_path)
+        has_build_test_command = config_content.match(/^\s*config\.build_test_command\s*=\s*["']([^"']+)["']/)
+        uses_test_helper = uses_react_on_rails_test_helper?
+
+        if File.exist?(shakapacker_yml)
+          shakapacker_content = File.read(shakapacker_yml)
+          # Match test section and look for compile: true
+          has_compile_true = shakapacker_content.match(/^test:.*?^\s+compile:\s*true/m)
+
+          if has_build_test_command && has_compile_true
+            checker.add_warning("  ⚠️  Both build_test_command and shakapacker compile: true are configured")
+            checker.add_info("  💡 These are mutually exclusive - use only one approach")
+            checker.add_info("  💡 Recommended: Use compile: true in shakapacker.yml (simpler)")
+            checker.add_info("  💡 Alternative: Use build_test_command with ReactOnRails::TestHelper (explicit control)")
+            checker.add_info("  📖 See: https://github.com/shakacode/react_on_rails/blob/master/docs/guides/testing-configuration.md")
+          elsif has_build_test_command && !uses_test_helper
+            checker.add_warning("  ⚠️  build_test_command is set but ReactOnRails::TestHelper is not configured")
+            checker.add_info("  💡 Add to spec/rails_helper.rb:")
+            checker.add_info("      ReactOnRails::TestHelper.configure_rspec_to_compile_assets(config)")
+            checker.add_info("  💡 Or remove build_test_command and use compile: true in shakapacker.yml")
+          elsif !has_build_test_command && uses_test_helper
+            checker.add_error("  🚫 ReactOnRails::TestHelper is configured but build_test_command is not set")
+            checker.add_info("  💡 Add to config/initializers/react_on_rails.rb:")
+            checker.add_info("      config.build_test_command = 'RAILS_ENV=test bin/shakapacker'")
+            checker.add_info("  💡 Or remove TestHelper and use compile: true in shakapacker.yml")
+          elsif !has_build_test_command && !has_compile_true && !uses_test_helper
+            checker.add_warning("  ⚠️  No test asset compilation configured")
+            checker.add_info("  💡 Recommended: Add to shakapacker.yml test section:")
+            checker.add_info("      compile: true")
+            checker.add_info("  📖 See: https://github.com/shakacode/react_on_rails/blob/master/docs/guides/testing-configuration.md")
+          elsif has_compile_true
+            checker.add_success("  ✅ Test assets configured via Shakapacker auto-compilation")
+            checker.add_info("      (compile: true in shakapacker.yml)")
+          elsif has_build_test_command && uses_test_helper
+            checker.add_success("  ✅ Test assets configured via React on Rails test helper")
+            checker.add_info("      (build_test_command + ReactOnRails::TestHelper)")
+          end
+        else
+          checker.add_warning("  ⚠️  config/shakapacker.yml not found")
+        end
+      rescue StandardError => e
+        checker.add_warning("  ⚠️  Could not analyze test configuration: #{e.message}")
+      end
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength
+
+    def uses_react_on_rails_test_helper?
+      spec_helpers = ["spec/rails_helper.rb", "spec/spec_helper.rb", "test/test_helper.rb"]
+      spec_helpers.any? do |helper|
+        next unless File.exist?(helper)
+
+        content = File.read(helper)
+        content.include?("configure_rspec_to_compile_assets") || content.include?("ensure_assets_compiled")
+      end
+    rescue StandardError
+      false
+    end
+
     def relativize_path(absolute_path)
       return absolute_path unless absolute_path.is_a?(String)
 
@@ -1144,6 +1267,130 @@ module ReactOnRails
         checker.add_info("  #{label}: <error reading value: #{e.message}>")
       end
     end
+
+    # Comment patterns used for filtering out commented async usage
+    ERB_COMMENT_PATTERN = /<%\s*#.*javascript_pack_tag/
+    HAML_COMMENT_PATTERN = /^\s*-#.*javascript_pack_tag/
+    SLIM_COMMENT_PATTERN = %r{^\s*/.*javascript_pack_tag}
+    HTML_COMMENT_PATTERN = /<!--.*javascript_pack_tag/
+
+    def check_async_usage
+      # When Pro is installed, async is fully supported and is the default behavior
+      # No need to check for async usage in this case
+      return if ReactOnRails::Utils.react_on_rails_pro?
+
+      async_issues = []
+
+      # Check 1: javascript_pack_tag with :async in view files
+      view_files_with_async = scan_view_files_for_async_pack_tag
+      unless view_files_with_async.empty?
+        async_issues << "javascript_pack_tag with :async found in view files:"
+        view_files_with_async.each do |file|
+          async_issues << "  • #{file}"
+        end
+      end
+
+      # Check 2: generated_component_packs_loading_strategy = :async
+      if config_has_async_loading_strategy?
+        async_issues << "config.generated_component_packs_loading_strategy = :async in initializer"
+      end
+
+      return if async_issues.empty?
+
+      # Report errors if async usage is found without Pro
+      checker.add_error("🚫 :async usage detected without React on Rails Pro")
+      async_issues.each { |issue| checker.add_error("  #{issue}") }
+      checker.add_info("  💡 :async can cause race conditions. Options:")
+      checker.add_info("    1. Upgrade to React on Rails Pro (recommended for :async support)")
+      checker.add_info("    2. Change to :defer or :sync loading strategy")
+      checker.add_info("  📖 https://www.shakacode.com/react-on-rails/docs/guides/configuration/")
+    end
+
+    def scan_view_files_for_async_pack_tag
+      view_patterns = ["app/views/**/*.erb", "app/views/**/*.haml", "app/views/**/*.slim"]
+      files_with_async = view_patterns.flat_map { |pattern| scan_pattern_for_async(pattern) }
+      files_with_async.compact
+    rescue Errno::ENOENT, Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError => e
+      # Log the error if Rails logger is available
+      log_debug("Error scanning view files for async: #{e.message}")
+      []
+    end
+
+    def scan_pattern_for_async(pattern)
+      Dir.glob(pattern).filter_map do |file|
+        next unless File.exist?(file)
+
+        content = File.read(file)
+        next if content_has_only_commented_async?(content)
+        next unless file_has_async_pack_tag?(content)
+
+        relativize_path(file)
+      end
+    end
+
+    def file_has_async_pack_tag?(content)
+      # Match javascript_pack_tag with :async symbol or async: true hash syntax
+      # Examples that should match:
+      #   - javascript_pack_tag "app", :async
+      #   - javascript_pack_tag "app", async: true
+      #   - javascript_pack_tag "app", :async, other_option: value
+      # Examples that should NOT match:
+      #   - javascript_pack_tag "app", defer: "async" (async is a string value, not the option)
+      #   - javascript_pack_tag "app", :defer
+      # Note: Theoretical edge case `data: { async: true }` would match but is extremely unlikely
+      # in real code and represents a harmless false positive (showing a warning when not needed)
+      # Use word boundary \b to ensure :async is not part of a longer symbol like :async_mode
+      # [^<]* allows matching across newlines within ERB tags but stops at closing ERB tag
+      content.match?(/javascript_pack_tag[^<]*(?::async\b|async:\s*true)/)
+    end
+
+    def content_has_only_commented_async?(content)
+      # Check if all occurrences of javascript_pack_tag with :async are in comments
+      # Returns true if ONLY commented async usage exists (no active async usage)
+
+      # First check if there's any javascript_pack_tag with :async in the full content
+      return true unless file_has_async_pack_tag?(content)
+
+      # Strategy: Remove all commented lines, then check if any :async remains
+      # This handles both single-line and multi-line tags correctly
+      uncommented_lines = content.each_line.reject do |line|
+        line.match?(ERB_COMMENT_PATTERN) ||
+          line.match?(HAML_COMMENT_PATTERN) ||
+          line.match?(SLIM_COMMENT_PATTERN) ||
+          line.match?(HTML_COMMENT_PATTERN)
+      end
+
+      uncommented_content = uncommented_lines.join
+      # If no async found in uncommented content, all async usage was commented
+      !file_has_async_pack_tag?(uncommented_content)
+    end
+
+    def config_has_async_loading_strategy?
+      config_path = "config/initializers/react_on_rails.rb"
+      return false unless File.exist?(config_path)
+
+      content = File.read(config_path)
+      # Check if generated_component_packs_loading_strategy is set to :async
+      # Filter out commented lines (lines starting with # after optional whitespace)
+      content.each_line.any? do |line|
+        # Skip lines that start with # (after optional whitespace)
+        next if line.match?(/^\s*#/)
+
+        # Match: config.generated_component_packs_loading_strategy = :async
+        # Use word boundary \b to ensure :async is the complete symbol, not part of :async_mode etc.
+        line.match?(/config\.generated_component_packs_loading_strategy\s*=\s*:async\b/)
+      end
+    rescue Errno::ENOENT, Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError => e
+      # Log the error if Rails logger is available
+      log_debug("Error checking async loading strategy: #{e.message}")
+      false
+    end
+
+    def log_debug(message)
+      return unless defined?(Rails.logger) && Rails.logger
+
+      Rails.logger.debug(message)
+    end
   end
   # rubocop:enable Metrics/ClassLength
 end

data/lib/react_on_rails/helper.rb

@@ -155,10 +155,10 @@ module ReactOnRails
     # props: Ruby Hash or JSON string which contains the properties to pass to the redux store.
     # Options
     #    defer: false -- pass as true if you wish to render this below your component.
-    #    immediate_hydration: false -- React on Rails Pro (licensed) feature. Pass as true if you wish to
-    #                        hydrate this store immediately instead of waiting for the page to load.
+    #    immediate_hydration: nil -- React on Rails Pro (licensed) feature. When nil (default), Pro users
+    #                        get immediate hydration, non-Pro users don't. Can be explicitly overridden.
     def redux_store(store_name, props: {}, defer: false, immediate_hydration: nil)
-      immediate_hydration = ReactOnRails.configuration.immediate_hydration if immediate_hydration.nil?
+      immediate_hydration = ReactOnRails::Utils.normalize_immediate_hydration(immediate_hydration, store_name, "Store")
 
       redux_store_data = { store_name: store_name,
                            props: props,
@@ -587,6 +587,15 @@ module ReactOnRails
           # It doesn't make any transformation, it listens and raises error if a chunk has errors
           chunk_json_result
         end
+
+        result.rescue do |err|
+          # This error came from the renderer
+          raise ReactOnRails::PrerenderError.new(component_name: react_component_name,
+                                                 # Sanitize as this might be browser logged
+                                                 props: sanitized_props_string(props),
+                                                 err: err,
+                                                 js_code: js_code)
+        end
       elsif result["hasErrors"] && render_options.raise_on_prerender_error
         raise_prerender_error(result, react_component_name, props, js_code)
       end