Document Redux shared store caveat with async: true

Added comprehensive documentation explaining why Redux shared stores
with inline component registration require defer: true instead of
async: true.

Changes:
- docs/streaming: Added "Important: Redux Shared Store Caveat" section
- docs/redux-store-api: Added IMPORTANT callout about script loading
- Explains the root cause: async scripts execute before inline scripts
- Provides 3 solutions: use defer, move registration to bundle, or use Pro

Root cause analysis:
With async: true, the bundle executes as soon as it downloads, which
can be before inline <script> tags in the HTML that register components.
This causes "Could not find component registered with name" errors.

With defer: true, scripts wait for HTML parsing to complete, ensuring
inline registration scripts run before the bundle attempts hydration.

React on Rails Pro's getOrWaitForStore can handle async loading by
waiting for registration to complete.

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

Co-Authored-By: Claude <noreply@anthropic.com>

Author: justin808

docs/api-reference/redux-store-api.md

@@ -4,6 +4,10 @@
 >
 > This Redux API is no longer recommended as it prevents dynamic code splitting for performance. Instead, you should use the standard `react_component` view helper passing in a "Render-Function."
 
+> [!IMPORTANT]
+>
+> **Script Loading Requirement:** If you use Redux shared stores with inline component registration (registering components in view templates with `<script>ReactOnRails.register({ MyComponent })</script>`), you **must use `defer: true`** in your `javascript_pack_tag` instead of `async: true`. With async loading, the bundle may execute before inline scripts, causing component registration failures. See the [Streaming Server Rendering documentation](../building-features/streaming-server-rendering.md#important-redux-shared-store-caveat) for details and alternatives.
+
 You don't need to use the `redux_store` api to use Redux. This API was set up to support multiple calls to `react_component` on one page that all talk to the same Redux store.
 
 If you are only rendering one React component on a page, as is typical to do a "Single Page App" in React, then you should _probably_ pass the props to your React component in a "Render-Function."

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

@@ -257,6 +257,25 @@ With Shakapacker ≥ 8.2.0, `async: true` is recommended even for non-streaming
 
 Note: `async: true` with the `immediate_hydration` feature allows components to hydrate during page load, improving TTI even without streaming. See the Immediate Hydration section below for configuration details.
 
+**⚠️ Important: Redux Shared Store Caveat**
+
+If you are using Redux shared stores with the `redux_store` helper and **inline script registration** (registering components in view templates with `<script>ReactOnRails.register({ MyComponent })</script>`), you must use `defer: true` instead of `async: true`:
+
+```erb
+<!-- ⚠️ REQUIRED for Redux shared stores with inline registration -->
+<%= javascript_pack_tag('client-bundle', 'data-turbo-track': 'reload', defer: true) %>
+```
+
+**Why?** With `async: true`, the bundle executes immediately upon download, potentially **before** inline `<script>` tags in the HTML execute. This causes component registration failures when React on Rails tries to hydrate the component.
+
+**Solutions:**
+
+1. **Use `defer: true`** - Ensures proper execution order (inline scripts run before bundle)
+2. **Move registration to bundle** - Register components in your JavaScript bundle instead of inline scripts (recommended)
+3. **Use React on Rails Pro** - Pro's `getOrWaitForStore` and `getOrWaitForStoreGenerator` can handle async loading with inline registration
+
+See the [Redux Store API documentation](../api-reference/redux-store-api.md) for more details on Redux shared stores.
+
 #### Why Async is Better Than No Defer
 
 With Shakapacker ≥ 8.2.0, using `async: true` provides the best performance: