Add doctor checks for unsafe async usage without Pro

Implements async usage detection in the doctor program to prevent race
conditions when using :async loading strategy or javascript_pack_tag
without React on Rails Pro.

Key features:
- Scans view files (.erb, .haml) for javascript_pack_tag with :async
- Checks config for generated_component_packs_loading_strategy = :async
- Skips validation when Pro is installed (async is safe and default)
- Reports errors when async used without Pro or immediate_hydration
- Reports warnings when immediate_hydration enabled but Pro not installed
- Provides clear, actionable error messages with upgrade guidance

Also updates generator template to comment out explicit
generated_component_packs_loading_strategy setting, allowing defaults
to "do the right thing" (:defer for non-Pro, :async for Pro).

Comprehensive test coverage added for all scenarios.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: justin808

docs/api-reference/configuration.md

@@ -267,11 +267,17 @@ ReactOnRails.configure do |config|
   config.make_generated_server_bundle_the_entrypoint = false
 
   # Configuration for how generated component packs are loaded.
-  # Options: :sync, :async, :defer
-  # - :sync (default for Shakapacker < 8.2.0): Loads scripts synchronously
-  # - :async (default for Shakapacker ≥ 8.2.0): Loads scripts asynchronously for better performance
-  # - :defer: Defers script execution until after page load
-  config.generated_component_packs_loading_strategy = :async
+  # Options: :defer (default), :sync, :async (Pro only)
+  #
+  # - :defer (default for non-Pro, recommended): Scripts load in parallel but execute in order
+  #   after HTML parsing. Prevents race conditions where components render before registration.
+  # - :sync: Scripts block HTML parsing while loading (not recommended, slowest option).
+  # - :async (Pro only): Scripts load and execute as soon as available. Requires Pro's
+  #   immediate_hydration feature to prevent race conditions.
+  #
+  # Default: :defer (non-Pro) or :async (Pro with Shakapacker >= 8.2.0)
+  # Note: Shakapacker >= 8.2.0 required for :async support
+  config.generated_component_packs_loading_strategy = :defer
 
   # DEPRECATED: Use `generated_component_packs_loading_strategy` instead.
   # Migration: `defer_generated_component_packs: true` → `generated_component_packs_loading_strategy: :defer`
@@ -289,11 +295,21 @@ ReactOnRails.configure do |config|
   #   their server-rendered HTML reaches the client, without waiting for the full page load.
   #   This improves time-to-interactive performance.
   #
+  # - generated_component_packs_loading_strategy = :async: Pro-only loading strategy that
+  #   works with immediate_hydration to load component scripts asynchronously for maximum
+  #   performance. Without Pro, :async can cause race conditions where components attempt
+  #   to hydrate before their JavaScript is loaded.
+  #
   # Example (in config/initializers/react_on_rails_pro.rb):
   #   ReactOnRailsPro.configure do |config|
   #     config.immediate_hydration = true
   #   end
   #
+  #   # In config/initializers/react_on_rails.rb:
+  #   ReactOnRails.configure do |config|
+  #     config.generated_component_packs_loading_strategy = :async
+  #   end
+  #
   # For more information, visit: https://www.shakacode.com/react-on-rails-pro
 
   ################################################################################

docs/core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md

@@ -47,6 +47,36 @@ config.auto_load_bundle = true
 > Example (dummy app): `auto_load_bundle` is set to `true` in the same initializer.
 > [Dummy initializer](https://github.com/shakacode/react_on_rails/blob/master/spec/dummy/config/initializers/react_on_rails.rb)
 
+### Configure `generated_component_packs_loading_strategy`
+
+The `generated_component_packs_loading_strategy` option controls how generated component packs are loaded in the browser. This affects the `async` and `defer` attributes on the `<script>` tags for your component bundles.
+
+Available options:
+
+- `:defer` (default, recommended): Scripts load in parallel but execute in order after HTML parsing. This prevents race conditions where components try to render before registration completes.
+- `:sync`: Scripts block HTML parsing while loading (not recommended, slowest option).
+- `:async`: Scripts load and execute as soon as available (**React on Rails Pro only**). Requires `immediate_hydration` to prevent race conditions.
+
+**IMPORTANT**: The `:async` loading strategy requires React on Rails Pro. Without Pro, `:async` can cause race conditions where components attempt to hydrate before their JavaScript is fully loaded. Pro's `immediate_hydration` feature ensures components hydrate safely with async loading.
+
+Configure in `config/initializers/react_on_rails.rb`:
+
+```rb
+# For most applications (Community and Pro)
+config.generated_component_packs_loading_strategy = :defer
+
+# For React on Rails Pro with immediate_hydration enabled
+# config.generated_component_packs_loading_strategy = :async
+```
+
+**Default behavior:**
+
+- Non-Pro: defaults to `:defer` (safe and performant)
+- Pro: defaults to `:async` (maximum performance with `immediate_hydration`)
+- Requires Shakapacker >= 8.2.0 for `:async` support
+
+See the [Configuration Guide](../api-reference/configuration.md#generated_component_packs_loading_strategy) for more details.
+
 ### Location of generated files
 
 Generated files will go to the following two directories:

docs/upgrading/release-notes/16.0.0.md

@@ -46,20 +46,22 @@ _The image above demonstrates the dramatic performance improvement:_
 
 - New configuration option `generated_component_packs_loading_strategy` replaces `defer_generated_component_packs`
 - Supports three loading strategies:
-  - `:async` - Loads scripts asynchronously (default for Shakapacker ≥ 8.2.0)
-  - `:defer` - Defers script execution until after page load (doesn't work well with Streamed HTML as it will wait for the full page load before hydrating the components)
-  - `:sync` - Loads scripts synchronously (default for Shakapacker < 8.2.0) (better to upgrade to Shakapacker 8.2.0 and use `:async` strategy)
+  - `:async` - Loads scripts asynchronously (**React on Rails Pro only**, default for Pro with Shakapacker ≥ 8.2.0). Requires `immediate_hydration` to prevent race conditions.
+  - `:defer` - Defers script execution until after page load (default for non-Pro, doesn't work well with Streamed HTML as it will wait for the full page load before hydrating the components)
+  - `:sync` - Loads scripts synchronously (not recommended, better to use `:defer` or upgrade to Pro for `:async`)
 - Improves page performance by optimizing how component packs are loaded
+- **IMPORTANT**: `:async` loading strategy requires React on Rails Pro. Without Pro, `:async` can cause race conditions where components attempt to hydrate before their JavaScript is fully loaded.
 
 ## Breaking Changes
 
 ### Component Hydration Changes
 
 - The `defer_generated_component_packs` configuration has been deprecated. Use `generated_component_packs_loading_strategy` instead.
-- The `generated_component_packs_loading_strategy` defaults to `:async` for Shakapacker ≥ 8.2.0 and `:sync` for Shakapacker < 8.2.0.
+- The `generated_component_packs_loading_strategy` defaults:
+  - **React on Rails Pro**: `:async` (requires Shakapacker ≥ 8.2.0)
+  - **Non-Pro**: `:defer` (safe default that prevents race conditions)
 - The `immediate_hydration` configuration now defaults to `false`. **Note: `immediate_hydration` is a React on Rails Pro (licensed) feature.**
-- When `generated_component_packs_loading_strategy: :async` and `immediate_hydration: true` are configured together, they optimize component hydration. Components hydrate as soon as their code and server-rendered HTML are available, without waiting for the full page to load. This parallel processing significantly improves time-to-interactive by eliminating the traditional waterfall of waiting for page load before beginning hydration (It's critical for streamed HTML).
-
+- When `generated_component_packs_loading_strategy: :async` and `immediate_hydration: true` are configured together (Pro only), they optimize component hydration. Components hydrate as soon as their code and server-rendered HTML are available, without waiting for the full page to load. This parallel processing significantly improves time-to-interactive by eliminating the traditional waterfall of waiting for page load before beginning hydration (It's critical for streamed HTML).
   - The previous need for deferring scripts to prevent race conditions has been eliminated due to improved hydration handling. Making scripts not defer is critical to execute the hydration scripts early before the page is fully loaded.
   - The `immediate_hydration` configuration (React on Rails Pro licensed feature) makes `react-on-rails` hydrate components immediately as soon as their server-rendered HTML reaches the client, without waiting for the full page load.
   - To enable optimized hydration, you can set `immediate_hydration: true` in your `config/initializers/react_on_rails.rb` file (requires React on Rails Pro license).
@@ -68,7 +70,6 @@ _The image above demonstrates the dramatic performance improvement:_
     - You can override this behavior for individual Redux stores by calling the `redux_store` helper with `immediate_hydration: true` or `immediate_hydration: false`, same as `react_component`.
 
 - `ReactOnRails.reactOnRailsPageLoaded()` is now an async function:
-
   - If you manually call this function to ensure components are hydrated (e.g., with async script loading), you must now await the promise it returns:
 
     ```js
@@ -87,7 +88,7 @@ _The image above demonstrates the dramatic performance improvement:_
 
 - If you were previously using `defer_generated_component_packs: true`, use `generated_component_packs_loading_strategy: :defer` instead
 - If you were previously using `defer_generated_component_packs: false`, use `generated_component_packs_loading_strategy: :sync` instead
-- For optimal performance with Shakapacker ≥ 8.2.0, consider using `generated_component_packs_loading_strategy: :async`
+- For optimal performance with Shakapacker ≥ 8.2.0 and React on Rails Pro, use `generated_component_packs_loading_strategy: :async` (requires Pro license and `immediate_hydration` to prevent race conditions)
 
 ### ESM-only package
 

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

@@ -69,15 +69,26 @@ ReactOnRails.configure do |config|
   # GENERATED COMPONENT PACKS LOADING STRATEGY
   ################################################################################
   # Configure how generated component packs are loaded in the browser.
-  # Options: :defer (default), :sync, :async
+  # Options: :defer (default), :sync, :async (Pro only)
   #
-  # - :defer (recommended for most apps): Scripts load in parallel but execute in order after HTML parsing
-  # - :sync: Scripts block HTML parsing (not recommended)
-  # - :async: Scripts load and execute as soon as available (requires React on Rails Pro for better performance)
+  # - :defer (recommended): Scripts load in parallel but execute in order after HTML parsing.
+  #   This prevents race conditions where components try to render before registration completes.
+  # - :sync: Scripts block HTML parsing while loading (not recommended, slowest option).
+  # - :async: Scripts load and execute as soon as available (React on Rails Pro only).
+  #   Requires immediate_hydration to prevent race conditions.
   #
-  # Default is :defer which provides good performance and prevents component registration race conditions.
-  # For React on Rails Pro users, :async can provide better performance by loading scripts asynchronously.
-  config.generated_component_packs_loading_strategy = :defer
+  # IMPORTANT: :async loading strategy requires React on Rails Pro. Without Pro, :async can cause
+  # race conditions where components attempt to hydrate before their JavaScript is fully loaded.
+  # Pro's immediate_hydration feature ensures components hydrate safely with async loading.
+  #
+  # Default behavior (recommended - no configuration needed):
+  # - Non-Pro: defaults to :defer (safe and performant)
+  # - Pro: defaults to :async (maximum performance with immediate_hydration)
+  #
+  # Only uncomment if you need to override the default:
+  # config.generated_component_packs_loading_strategy = :defer
+  #
+  # See: https://www.shakacode.com/react-on-rails/docs/guides/configuration.html#generated_component_packs_loading_strategy
 
   ################################################################################
   # REACT ON RAILS PRO FEATURES

lib/react_on_rails/doctor.rb

@@ -173,6 +173,7 @@ def check_development
       check_procfile_dev
       check_bin_dev_script
       check_gitignore
+      check_async_usage
     end
 
     def check_javascript_bundles
@@ -1144,6 +1145,94 @@ def safe_display_config_value(label, config, method_name)
         checker.add_info("  #{label}: <error reading value: #{e.message}>")
       end
     end
+
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
+    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
+      # Note: immediate_hydration alone is not sufficient - Pro is required for safe async usage
+      immediate_hydration_enabled = check_immediate_hydration_enabled?
+
+      if immediate_hydration_enabled
+        checker.add_warning("⚠️  Using :async without React on Rails Pro may cause race conditions")
+        async_issues.each { |issue| checker.add_warning("  #{issue}") }
+        checker.add_info("  💡 immediate_hydration is enabled but Pro gem is not installed")
+        checker.add_info("  💡 For production-safe async loading, upgrade to React on Rails Pro")
+      else
+        checker.add_error("🚫 :async usage detected without proper configuration")
+        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
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity
+
+    def scan_view_files_for_async_pack_tag
+      files_with_async = []
+
+      # Scan app/views for .erb and .haml files
+      view_patterns = ["app/views/**/*.erb", "app/views/**/*.haml"]
+
+      view_patterns.each do |pattern|
+        Dir.glob(pattern).each do |file|
+          next unless File.exist?(file)
+
+          content = File.read(file)
+          # Look for javascript_pack_tag with :async or "async"
+          if content.match?(/javascript_pack_tag.*:async/) || content.match?(/javascript_pack_tag.*["']async["']/)
+            files_with_async << relativize_path(file)
+          end
+        end
+      end
+
+      files_with_async
+    rescue StandardError
+      []
+    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
+      content.match?(/config\.generated_component_packs_loading_strategy\s*=\s*:async/)
+    rescue StandardError
+      false
+    end
+
+    def check_immediate_hydration_enabled?
+      # Check if immediate_hydration is enabled in configuration
+      return false unless defined?(ReactOnRails)
+
+      config = ReactOnRails.configuration
+      config.immediate_hydration == true
+    rescue StandardError
+      false
+    end
   end
   # rubocop:enable Metrics/ClassLength
 end

packages/react-on-rails/src/context.ts

@@ -1,10 +1,10 @@
 import type { ReactOnRailsInternal, RailsContext } from './types/index.ts';
 
 declare global {
-  /* eslint-disable vars-on-top,no-var,no-underscore-dangle */
+  /* eslint-disable vars-on-top,no-underscore-dangle */
   var ReactOnRails: ReactOnRailsInternal | undefined;
   var __REACT_ON_RAILS_EVENT_HANDLERS_RAN_ONCE__: boolean;
-  /* eslint-enable vars-on-top,no-var,no-underscore-dangle */
+  /* eslint-enable vars-on-top,no-underscore-dangle */
 }
 
 let currentRailsContext: RailsContext | null = null;