Recommend async + immediate_hydration even for non-streaming pages

- Update documentation to clarify that defer: true is suboptimal even for non-streaming pages
- Recommend async: true with immediate_hydration for best Time to Interactive
- Add section about generated_component_packs_loading_strategy config
- Update dummy app comment to explain why defer is used (test compatibility) but async is recommended for production

Co-authored-by: Abanoub Ghadban <AbanoubGhadban@users.noreply.github.com>

Author: github-actions[bot]

docs/building-features/streaming-server-rendering.md

@@ -236,36 +236,63 @@ With `defer: true`, your streamed components will:
 
 #### Recommended Approaches
 
-**For Pages WITH Streaming Components:**
+**For All Pages (With or Without Streaming Components):**
 
 ```erb
-<!-- ✅ GOOD: No defer - allows Selective Hydration to work -->
-<%= javascript_pack_tag('client-bundle', 'data-turbo-track': 'reload', defer: false) %>
-
-<!-- ✅ BEST: Use async for even faster hydration (requires Shakapacker ≥ 8.2.0) -->
+<!-- ✅ BEST: Use async with immediate_hydration (requires Shakapacker ≥ 8.2.0 and React on Rails Pro) -->
 <%= javascript_pack_tag('client-bundle', 'data-turbo-track': 'reload', async: true) %>
 ```
 
-**For Pages WITHOUT Streaming Components:**
+With `async: true` and the `immediate_hydration` Pro feature enabled, your components hydrate as soon as they're available—before the full page finishes loading. This provides optimal Time to Interactive (TTI) for both streaming and non-streaming pages.
+
+**Alternative for Non-Pro or Pre-8.2.0 Shakapacker:**
+
+```erb
+<!-- ✅ GOOD: No defer - allows components to hydrate early -->
+<%= javascript_pack_tag('client-bundle', 'data-turbo-track': 'reload', defer: false) %>
+```
+
+**⚠️ Not Recommended (Even for Non-Streaming Pages):**
 
 ```erb
-<!-- ✅ OK: defer is fine when not using streaming -->
+<!-- ⚠️ defer delays hydration until full page load - suboptimal even without streaming -->
 <%= javascript_pack_tag('client-bundle', 'data-turbo-track': 'reload', defer: true) %>
 ```
 
-#### Why Async is Better Than No Defer
+While `defer: true` won't defeat Selective Hydration on non-streaming pages (since there's no streaming to defeat), it still delays all component hydration until after the complete page loads, resulting in slower Time to Interactive.
+
+#### Using generated_component_packs_loading_strategy Config
+
+Instead of manually specifying `async: true` on each `javascript_pack_tag`, you can configure the loading strategy globally for auto-generated component packs:
+
+```ruby
+# config/initializers/react_on_rails.rb
+ReactOnRails.configure do |config|
+  # Set loading strategy for auto-generated component packs
+  # Options: :sync, :async, :defer
+  config.generated_component_packs_loading_strategy = :async
+
+  # Enable immediate hydration (React on Rails Pro feature)
+  # Components hydrate as soon as their HTML arrives, without waiting for full page load
+  config.immediate_hydration = true
+end
+```
+
+This configuration applies to components rendered with auto-generated packs. For manual `javascript_pack_tag` calls, you'll still need to specify `async: true` explicitly.
+
+#### Why Async is Better
 
-With Shakapacker ≥ 8.2.0, using `async: true` provides the best performance:
+With Shakapacker ≥ 8.2.0 and React on Rails Pro, using `async: true` + `immediate_hydration: true` provides the best performance:
 
-- **No defer/async**: Scripts block HTML parsing and streaming
-- **defer: true**: Scripts wait for complete page load (defeats Selective Hydration)
-- **async: true**: Scripts load in parallel and execute ASAP, enabling:
-  - Selective Hydration to work immediately
-  - Components to become interactive as they stream in
-  - Optimal Time to Interactive (TTI)
+- **defer: true**: Scripts wait for complete page load, delaying all hydration
+- **No defer/async**: Scripts block HTML parsing
+- **async: true + immediate_hydration: true**: Scripts load in parallel and components hydrate immediately, enabling:
+  - Fastest Time to Interactive (TTI)
+  - Selective Hydration for streaming components
+  - Early hydration for all components (streaming or not)
 
 #### Migration Timeline
 
-1. **Before Shakapacker 8.2.0**: Use `defer: false` for streaming pages
-2. **Shakapacker ≥ 8.2.0**: Migrate to `async: true` for streaming pages
-3. **Non-streaming pages**: Can continue using `defer: true` safely (regardless of Shakapacker version)
+1. **Before Shakapacker 8.2.0 or without React on Rails Pro**: Use `defer: false`
+2. **Shakapacker ≥ 8.2.0 + React on Rails Pro**: Use `async: true` with `immediate_hydration: true` for optimal performance
+3. **Avoid `defer: true`**: Even for non-streaming pages, defer delays hydration unnecessarily

spec/dummy/app/views/layouts/application.html.erb

@@ -9,10 +9,12 @@
 
   <%= yield :head %>
 
-  <%# defer: true is safe here because this app does NOT use streaming server rendering.
-      defer also ensures scripts load in the correct order when using auto-generated component packs.
-      For apps with streaming components, use defer: false or async: true to enable
-      React 18's Selective Hydration. See docs/building-features/streaming-server-rendering.md %>
+  <%# Note: Using defer: true here, but async: true with immediate_hydration is recommended for better
+      Time to Interactive (TTI), even for non-streaming pages. This app keeps defer: true to maintain
+      test compatibility and demonstrate that defer works when streaming is not used.
+      For production apps, prefer async: true with immediate_hydration (React on Rails Pro + Shakapacker ≥ 8.2.0),
+      or use generated_component_packs_loading_strategy: :async in your initializer.
+      See docs/building-features/streaming-server-rendering.md %>
   <%= javascript_pack_tag('client-bundle', 'data-turbo-track': 'reload', defer: true) %>
 
   <%= csrf_meta_tags %>