docs: remove stale immediate_hydration references (#3139) (#3159)

## Summary

The `immediate_hydration` option was removed from the codebase in #2834.
The behavior it controlled (Pro users hydrate components before
`DOMContentLoaded`) still exists, but it's now always-on for Pro and
always-off for OSS — there is no per-component toggle.

Several docs still presented `immediate_hydration` as a configurable
option, which confused users who tried to set it and found it didn't
exist. This PR reframes those sections as descriptions of Pro's built-in
early hydration behavior and drops stale code examples.

### Files updated

- `docs/pro/streaming-ssr.md` — renamed "Immediate Hydration" to "Early
Hydration (Pro)"; reworded surrounding prose; removed the
`immediate_hydration: false` code example; updated migration-timeline
bullet
- `docs/pro/troubleshooting.md` — removed the "Verify
`immediate_hydration` option" bullet from the hydration-failure
checklist
- `docs/oss/building-features/turbolinks.md` — reframed the Turbo
Streams section (Pro's early hydration is automatic, not a per-call
option); removed `immediate_hydration: true` from the code example;
reworded the async+Turbolinks warning box; removed the v16.0 migration
note that referenced the removed option; fixed GitHub `[!WARNING]` alert
syntax so the callout renders
- `docs/oss/api-reference/ruby-api-pro.md` — removed
`:immediate_hydration` from the `stream_react_component` options list
and split the options/hydration note for clarity
- `docs/oss/configuration/configuration-deprecated.md` — tightened the
migration step (delete both config and per-component
`immediate_hydration:` keys — all are no-ops) and corrected the removal
version to v16.6.0
- `docs/oss/upgrading/release-notes/16.2.0.md` — dropped the stale "use
component-level overrides if needed" hint from the troubleshooting
section (per-component keys were also removed in v16.6.0). The
historical "Component-level overrides still work" section is preserved
as-is since it accurately describes behavior at the 16.2.0 release
point.

### Files intentionally left alone

Per the issue, release notes and migration guidance still correctly
reference `immediate_hydration` as a historical/deprecated option:
- `docs/oss/upgrading/release-notes/16.0.0.md`
- `docs/oss/configuration/README.md`
- `docs/oss/upgrading/upgrading-react-on-rails.md` (migration guidance)

Fixes #3139

## Test plan

- [x] `grep -rn immediate_hydration docs/pro docs/oss/building-features
docs/oss/api-reference` returns no live/example references (only
migration/deprecation guidance remains in upgrade-notes and deprecation
docs, as intended)
- [x] Prettier formatting passes on edited files
- [x] pre-commit hooks (trailing newlines, markdown link check,
prettier) all pass
- [ ] Reviewer: visually scan the updated sections in `streaming-ssr.md`
and `turbolinks.md` to confirm the reframing reads well

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

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: justin808

docs/oss/api-reference/ruby-api-pro.md

@@ -47,9 +47,9 @@ Streams a server-rendered React component using React 18's `renderToPipeableStre
 
 Requires the controller to use `stream_view_containing_react_components`.
 
-Options: same as `react_component` plus:
+Options: same as `react_component`.
 
-- `:immediate_hydration` (default: `true`) — controls hydration timing
+> **Note (Pro):** React on Rails Pro hydrates streamed components early (before `DOMContentLoaded`) automatically — no per-component toggle is exposed.
 
 ```ruby
 <%= stream_react_component("App", props: { data: @data }) %>

docs/oss/building-features/turbolinks.md

@@ -129,11 +129,11 @@ Use `content_for` to render your body content first, capturing auto-appends befo
 
 > **⚡️ React on Rails Pro Feature**
 >
-> Turbo Streams require the `immediate_hydration: true` option, which is a [React on Rails Pro](../../pro/react-on-rails-pro.md) licensed feature.
+> Turbo Streams rely on Pro's early hydration behavior, which hydrates components as soon as they are inserted into the DOM. This is a [React on Rails Pro](../../pro/react-on-rails-pro.md) licensed feature that is always on for Pro users.
 
 **Why Turbo Streams Need Special Handling:**
 
-Unlike Turbo Frames, Turbo Streams don't dispatch the normal `turbo:render` events that React on Rails uses to hydrate components. Instead, they directly manipulate the DOM. The `immediate_hydration` option tells React on Rails to hydrate the component immediately when it's inserted into the DOM, without waiting for page load events.
+Unlike Turbo Frames, Turbo Streams don't dispatch the normal `turbo:render` events that React on Rails uses to hydrate components. Instead, they directly manipulate the DOM. React on Rails Pro hydrates components immediately when they are inserted into the DOM, without waiting for page load events, so Turbo Stream updates work out of the box.
 
 **Example: Create a Turbo Stream Response**
 
@@ -147,9 +147,7 @@ Unlike Turbo Frames, Turbo Streams don't dispatch the normal `turbo:render` even
 ```erb
 <%# app/views/items/create.turbo_stream.erb - Turbo Stream response %>
 <%= turbo_stream.update 'item-list' do %>
-  <%= react_component("ItemList",
-                      props: @items,
-                      immediate_hydration: true) %>
+  <%= react_component("ItemList", props: @items) %>
 <% end %>
 ```
 
@@ -158,17 +156,14 @@ Unlike Turbo Frames, Turbo Streams don't dispatch the normal `turbo:render` even
 1. User clicks "Load Items" button
 2. Rails responds with `create.turbo_stream.erb`
 3. Turbo Stream updates the `item-list` frame with the new React component
-4. `immediate_hydration: true` ensures the component hydrates immediately
+4. React on Rails Pro hydrates the inserted component immediately
 
 **Learn More:**
 
-- See [v16.0 Release Notes](../upgrading/release-notes/16.0.0.md#enhanced-script-loading-strategies) for full `immediate_hydration` documentation
 - See [Streaming Server Rendering](./streaming-server-rendering.md) for another Pro use case
 - Working example in codebase: `react_on_rails/spec/dummy/app/views/pages/turbo_stream_send_hello_world.turbo_stream.erb`
 - Contact [justin@shakacode.com](mailto:justin@shakacode.com) for React on Rails Pro licensing
 
-**Migration Note:** If you're referencing [PR #1620](https://github.com/shakacode/react_on_rails/pull/1620) discussions, note that `force_load` was renamed to `immediate_hydration` in v16.0.
-
 ## Legacy Turbolinks Support
 
 _The following documentation covers older Turbolinks versions (2.x and 5.x). While still supported by React on Rails, we recommend migrating to Turbo when possible._
@@ -259,17 +254,18 @@ document.addEventListener('turbolinks:load', function () {
 
 React on Rails 15 fixes both issues, so if you still have the listener it can be removed (and should be as `reactOnRailsPageLoaded()` is now async).
 
-> [!WARNING] > **Async Scripts with Turbolinks Require Pro Feature**
+> [!WARNING]
+> **Async Scripts with Turbolinks Require Pro**
 >
-> If you use async script loading with Turbolinks, you must enable `immediate_hydration: true` to prevent race conditions. This is a React on Rails Pro feature.
+> If you use async script loading with Turbolinks, you need Pro's early hydration behavior to prevent race conditions. This is a React on Rails Pro licensed feature.
 >
-> Without `immediate_hydration: true`, async scripts may not be ready when Turbolinks fires navigation events, causing components to fail hydration.
+> Without Pro's early hydration, async scripts may not be ready when Turbolinks fires navigation events, causing components to fail hydration.
 >
 > **Alternatives:**
 >
 > - Use `defer` instead of `async` (waits for full page load before hydration)
 > - Upgrade to modern Turbo (recommended)
-> - Use React on Rails Pro for `immediate_hydration: true`
+> - Use React on Rails Pro (early hydration is automatic for Pro users)
 
 ### Turbolinks 5 Specific Information
 

docs/oss/configuration/configuration-deprecated.md

@@ -8,18 +8,11 @@ For current configuration options, see [Configuration](README.md).
 
 ### immediate_hydration
 
-**Status:** ⚠️ REMOVED in v17.0
+**Status:** ⚠️ REMOVED in v16.6.0
 
-This configuration option has been removed. Immediate hydration is now automatically enabled for Pro users and disabled for non-Pro users.
+This configuration option has been removed. React on Rails Pro now performs early hydration automatically for streamed components; there is no per-component toggle. Non-Pro users are not affected.
 
-**Migration:** Remove any `config.immediate_hydration` lines from your configuration. Use per-component overrides if needed:
-
-```ruby
-# Pro users can disable for specific components:
-react_component("MyComponent", immediate_hydration: false)
-
-# Non-Pro users: immediate_hydration is ignored
-```
+**Migration:** Remove any `config.immediate_hydration` lines from your configuration and any `immediate_hydration:` keys passed to `react_component` / `stream_react_component` — both are no-ops and can be safely deleted.
 
 See [CHANGELOG.md](https://github.com/shakacode/react_on_rails/blob/main/CHANGELOG.md) for details.
 

docs/oss/upgrading/release-notes/16.2.0.md

@@ -276,7 +276,7 @@ bundle show react_on_rails
 
 **Cause:** The global config option is now deprecated and has no effect.
 
-**Solution:** Remove `config.immediate_hydration` from your initializer. The setting is now automatic (enabled for Pro users, disabled for non-Pro). Use component-level overrides if needed.
+**Solution:** Remove `config.immediate_hydration` from your initializer. The setting is now automatic (enabled for Pro users, disabled for non-Pro).
 
 ## Related Resources
 

docs/pro/streaming-ssr.md

@@ -293,11 +293,11 @@ With `defer: true`, your streamed components will:
 With Shakapacker ≥ 8.2.0, `async: true` is recommended even for non-streaming pages to improve Time to Interactive (TTI):
 
 ```erb
-<!-- ✅ RECOMMENDED: Use async with immediate_hydration for optimal performance -->
+<!-- ✅ RECOMMENDED: Use async for optimal performance -->
 <%= javascript_pack_tag('client-bundle', 'data-turbo-track': 'reload', async: true) %>
 ```
 
-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.
+Note: With React on Rails Pro, `async: true` allows components to hydrate during page load, improving TTI even without streaming. See the Early Hydration section below for details.
 
 **⚠️ Important: Redux Shared Store Caveat**
 
@@ -333,28 +333,20 @@ With Shakapacker ≥ 8.2.0, using `async: true` provides the best performance:
 
 1. **Before Shakapacker 8.2.0**: Use `defer: false` for streaming pages
 2. **Shakapacker ≥ 8.2.0**: Migrate to `async: true` for all pages (streaming and non-streaming)
-3. **Enable `immediate_hydration`**: Configure for optimal Time to Interactive (see section below)
+3. **Early Hydration (Pro)**: Pro hydrates components early for optimal Time to Interactive — no additional configuration needed (see section below)
 
-## Immediate Hydration
+## Early Hydration (Pro)
 
-React on Rails Pro automatically enables the `immediate_hydration` feature, which allows components to hydrate during the page loading state (before DOMContentLoaded). This works optimally with `async: true` scripts.
+React on Rails Pro hydrates components during the page loading state (before `DOMContentLoaded`), rather than waiting for the full page load. This works optimally with `async: true` scripts and is always on for Pro — there is no configuration toggle.
 
-**Benefits of `immediate_hydration` with `async: true`:**
+**Benefits of early hydration with `async: true`:**
 
 - Components become interactive as soon as their JavaScript loads
-- No need to wait for DOMContentLoaded or full-page load
+- No need to wait for `DOMContentLoaded` or full-page load
 - Optimal Time to Interactive (TTI) for both streaming and non-streaming pages
 - Works seamlessly with React's Selective Hydration
 
-**Note:** The `immediate_hydration` feature requires a React on Rails Pro license. It is enabled automatically — no configuration needed.
-
-**Component-Level Control:**
-
-You can disable immediate hydration for specific components:
-
-```erb
-<%= react_component('MyComponent', props: {}, immediate_hydration: false) %>
-```
+**Note:** Early hydration requires a React on Rails Pro license. It is always enabled for Pro users and unavailable in OSS — no per-component toggle is exposed.
 
 **generated_component_packs_loading_strategy Option:**
 

docs/pro/troubleshooting.md

@@ -97,5 +97,4 @@ For issues related to upgrading from GitHub Packages to public distribution, see
 **Fixes**:
 
 - Check that client-side JavaScript bundles are loaded (no 404s in browser console)
-- Verify `immediate_hydration` option — set to `true` for immediate hydration
 - Ensure client components have the `'use client'` directive