Walkthrough

Removed references and examples for the removed immediate_hydration option across Pro and OSS docs; replaced them with language stating React on Rails Pro performs early hydration automatically for streamed components and updated migration and troubleshooting guidance accordingly. (Documentation-only changes.)

Changes

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 I hopped through lines and nudged an old flag free,
Morning hydration now starts automatically.
No knobs to twiddle, no examples to mend,
Docs neat as a burrow from start to end. 🥕✨

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Code Review

Summary: Documentation-only cleanup that removes stale immediate_hydration references from live docs and accurately reframes the behavior as Pro's always-on early hydration. No runtime code is touched.

What's Good

• The scope is well-defined: live/example docs are updated; release notes and deprecation docs are correctly left alone.
• Every removal is accurate — immediate_hydration was removed in Remove immediate_hydration feature from codebase #2834 and the per-component toggle no longer exists.
• The new prose ("always on for Pro — no per-component toggle is exposed") is clear and prevents the user confusion described in Remove stale immediate_hydration references from docs #3139.
• The ruby-api-pro.md rewrite is tight: drops the stale option list and replaces it with a single descriptive sentence.
• The troubleshooting checklist bullet was correctly removed — telling users to "set immediate_hydration: true" was actively misleading.

Minor Nit (pre-existing, touched by this PR)

In docs/oss/building-features/turbolinks.md, the GitHub alert callout has [!WARNING] on the same line as the heading:

> [!WARNING] > **Async Scripts with Turbolinks Require Pro**

GitHub's alert syntax expects [!WARNING] alone on the first line:

> [!WARNING]
> **Async Scripts with Turbolinks Require Pro**

This was pre-existing and the PR only changed the title text, so it's fine to leave it for a follow-up. Worth noting since GitHub renders the two forms differently.

Verdict

✅ Approve. The changes are accurate, well-scoped, and directly fix the user confusion reported in #3139. The test plan grep confirms no live references remain in the targeted directories.

Greptile Summary

This PR removes stale immediate_hydration references from four documentation files, replacing them with accurate descriptions of Pro's always-on early hydration behavior (which has been unconditionally enabled since #2834). The rewording is consistent across all four files and correctly distinguishes between the Pro feature (always on) and OSS (unavailable), with no per-component toggle implied.

Confidence Score: 5/5

Safe to merge — documentation-only change with no code impact.

All four changed files are docs-only. The rewording accurately reflects the actual behavior (Pro always-on, OSS unavailable, no per-component toggle). Prose is internally consistent and no immediate_hydration references leak into the updated sections. No P0 or P1 findings.

No files require special attention.

Important Files Changed

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[React Component Inserted into DOM] --> B{React on Rails Edition?}
    B -->|Pro| C[Early Hydration — before DOMContentLoaded\nalways on, no toggle]
    B -->|OSS| D[Standard Hydration — waits for\npage load events]
    C --> E[Component Interactive]
    D --> F[DOMContentLoaded fires]
    F --> E

_{Reviews (1): Last reviewed commit: "docs: remove stale immediate_hydration r..." | Re-trigger Greptile}

Code Review

Summary: Clean, focused documentation cleanup. Removes stale immediate_hydration references from active docs while correctly preserving them in release notes, upgrade guides, and the deprecation config page. Low risk — no runtime changes.

What works well

• The scope boundary is well-reasoned: active docs updated, historical/upgrade docs intentionally left alone
• The reframing from "configurable option" to "always-on Pro behavior" is applied consistently across all four changed files
• The grep test plan is solid — confirmed: zero live references remain in docs/pro, docs/oss/building-features, and docs/oss/api-reference
• Removal of the troubleshooting checklist item is correct; telling users to "set immediate_hydration: true" was actively harmful

Issues

configuration-deprecated.md — migration guidance now misleads (outside PR scope, but worth a follow-up)

The file was intentionally left alone, but its current content reads:

# Pro users can disable for specific components:
react_component("MyComponent", immediate_hydration: false)

This directly contradicts the new docs which state "no per-component toggle is exposed." A Pro user following this migration path would get a deprecation warning and be silently ignored. The fix is a one-line edit changing "Pro users can disable for specific components" to a note that per-component overrides are also no longer supported. Suggest a follow-up issue or a quick amendment to this PR.

turbolinks.md line ~257 — malformed GFM alert syntax (pre-existing, touched by this PR)

The PR renamed the alert title on this line but left the syntax broken:

> [!WARNING] > **Async Scripts with Turbolinks Require Pro**

GitHub's alert blocks require [!WARNING] to occupy its own line:

> [!WARNING]
> **Async Scripts with Turbolinks Require Pro**

The current form renders > **Title** as literal text inside the warning badge rather than as formatted content. Since this line was already in the diff, it would be clean to fix it here.

Minor observations

• streaming-ssr.md migration timeline step 3 now reads "Use React on Rails Pro" — slightly awkward since Pro is a prerequisite of the entire section, not a migration step. "Pro hydrates components early — no additional configuration needed" or simply removing the step would read more naturally.
• The ruby-api-pro.md change is clean and precise.

Verdict: Approve with the suggestion to fix the [!WARNING] syntax before merge (trivial one-line fix) and track the configuration-deprecated.md contradiction as a follow-up.

Review comment triage

Addressed:

• @claude[bot] inline nit on docs/oss/building-features/turbolinks.md:257 — split [!WARNING] onto its own line so GitHub's alert callout renders correctly. Fixed in f207a16; thread resolved.

No action (rationale):

• @coderabbitai[bot] walkthrough — auto-generated summary/pre-merge check post; no actionable items.
• @claude[bot] approval summary — ✅ approve with confidence; the only nit flagged is the inline comment above (now addressed).
• @greptile-apps[bot] — 5/5 confidence, docs-only change, no findings.

No further changes needed; PR is ready for merge review.

@justin808 Thanks for the thorough triage summary! The fix for the [!WARNING] callout rendering (f207a16) addresses the only outstanding nit. The docs-only changes look clean — stale immediate_hydration references removed, historical/deprecation docs preserved, and the Early Hydration (Pro) behavior correctly described as always-on for Pro / unavailable for OSS. Ready for merge. 🚀

Learnt from: CR
Repo: shakacode/react_on_rails PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-21T08:53:17.309Z
Learning: For small, focused PRs (roughly 5 files or fewer with one clear purpose): use at most one AI reviewer for inline comments, batch review fixes into one follow-up push, and verify language/runtime/library claims locally before making code changes in response to AI review

Learnt from: CR
Repo: shakacode/react_on_rails PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-12T23:15:11.806Z
Learning: For small, focused PRs (5 files changed or fewer with one clear purpose): use at most one AI reviewer that leaves inline comments; additional AI tools should be summary-only or used manually

Learnt from: CR
Repo: shakacode/react_on_rails PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-10T04:25:56.848Z
Learning: Refer to AGENTS.md for canonical policy on commands, tests, lint workflow, formatting, style requirements, Git/PR safety boundaries, and project directory boundaries. If CLAUDE.md conflicts with AGENTS.md, follow AGENTS.md

Learnt from: justin808
Repo: shakacode/react_on_rails PR: 2651
File: docs/oss/introduction.md:47-47
Timestamp: 2026-03-26T02:20:12.940Z
Learning: In `docs/oss/introduction.md` (and related docs in the `shakacode/react_on_rails` repo), the link to `docs/oss/getting-started/comparison-with-alternatives.md` described as "a side-by-side matrix with benchmarks" is intentionally and accurately worded. The page includes actual benchmark sections (e.g., Vite vs Rspack benchmark tables), so the phrase "with benchmarks" should NOT be flagged as misleading in future reviews.

Learnt from: justin808
Repo: shakacode/react_on_rails PR: 2789
File: docs/pro/streaming-ssr.md:79-81
Timestamp: 2026-03-21T23:48:01.271Z
Learning: In React on Rails Pro, `stream_react_component` (defined in `react_on_rails_pro_helper.rb` around lines 127-129) forces `prerender: true` internally. The option is not configurable by callers, so documentation examples should NOT include `prerender: true` in `stream_react_component` invocations as it is misleading.

Learnt from: AbanoubGhadban
Repo: shakacode/react_on_rails PR: 1781
File: node_package/src/ClientSideRenderer.ts:82-95
Timestamp: 2025-09-15T21:24:48.207Z
Learning: In React on Rails, the force_load feature includes both explicit `data-force-load="true"` usage and the ability to hydrate components during the page loading state (`document.readyState === 'loading'`). Both capabilities require a Pro license, so the condition `!railsContext.rorPro && (isComponentForceLoaded || document.readyState === 'loading')` correctly gates both scenarios.

Learnt from: justin808
Repo: shakacode/react_on_rails PR: 0
File: :0-0
Timestamp: 2026-04-13T02:29:20.920Z
Learning: In `react_on_rails_pro/lib/react_on_rails_pro/engine.rb` and `react_on_rails/lib/react_on_rails/configuration.rb` (PR `#3094`): Do NOT reset `rendering_strategy` or `js_code_builder` inside `ReactOnRails.configure`. The Pro engine sets these exactly once during `after_initialize`; resetting them on reconfigure would silently drop Pro's NodeStrategy/ProJsCodeBuilder assignments. A proper reconfigure mechanism for these accessors is deferred to Step 3 of the strategy-pattern refactor (`#2905`).

Learnt from: justin808
Repo: shakacode/react_on_rails PR: 2886
File: docs/sidebars.ts:9-251
Timestamp: 2026-03-29T08:38:50.670Z
Learning: In the `shakacode/react_on_rails` repository, `docs/sidebars.ts` uses sidebar doc IDs **without** an `oss/` prefix (e.g., `'api-reference/javascript-api'`, `'building-features/caching'`). Although OSS doc files are physically located at `docs/oss/...`, Docusaurus is configured to remap that path so those IDs resolve correctly without the prefix. Pro docs use the `pro/` prefix (e.g., `'pro/react-on-rails-pro'`). Do not suggest adding an `oss/` prefix to sidebar IDs in this repo.

Learnt from: justin808
Repo: shakacode/react_on_rails PR: 2530
File: react_on_rails_pro/lib/react_on_rails_pro/concerns/stream.rb:0-0
Timestamp: 2026-03-04T23:37:22.169Z
Learning: In `react_on_rails_pro/lib/react_on_rails_pro/concerns/stream.rb`, the `stream_view_containing_react_components` method intentionally does NOT set `Cache-Control: no-transform`. The PR `#2530` is an alternative fix for the Live streaming + compression middleware deadlock (issue `#2519`): instead of using `no-transform` to make compression middleware short-circuit, gzip is handled in-process via a custom `GzipOutputStream` class wrapping `Zlib::GzipWriter`. This keeps compression enabled for clients that support gzip while bypassing the middleware stack entirely. Do not suggest adding `Cache-Control: no-transform` to this method.

Learnt from: justin808
Repo: shakacode/react_on_rails PR: 2610
File: docs/pro/react-server-components/create-without-ssr.md:13-22
Timestamp: 2026-03-24T21:38:26.825Z
Learning: In `docs/pro/react-server-components/create-without-ssr.md`, JS install instructions for React on Rails Pro should only install `react-on-rails-pro` (not `react-on-rails` separately), because the Pro package already includes the base package functionality. Use `--exact` (yarn/pnpm) or `--save-exact` (npm) flags to pin to an exact version for reproducibility.

Learnt from: CR
Repo: shakacode/react_on_rails PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-12T23:15:11.806Z
Learning: Applies to CHANGELOG.md : Changelog format: `[PR 1818](https://github.com/shakacode/react_on_rails/pull/1818) by [username](https://github.com/username)` (no hash before PR number)

Thanks for the triage summary. Everything looks good — the [!WARNING] rendering fix is the only nit that needed attention, and that's addressed. PR is clear from my side. ✅

Code Review

Overall: Clean, well-scoped documentation fix. The test plan's grep check passes — no live immediate_hydration references remain in the targeted files.

What the PR does well

• Correctly distinguishes between live docs (updated) and release notes / deprecation guides (intentionally left alone). Historical context belongs in upgrade notes, not in the current API reference.
• The prose in the refactored sections reads clearly. "Early Hydration (Pro)" is a better heading than "Immediate Hydration" because it names the observable behavior, not the removed option.
• Bonus fix: the malformed GitHub-flavored markdown admonition in turbolinks.md (> [!WARNING] > **...** on a single line) is now properly split across two lines. This was a rendering bug in the old docs.
• The removal of the stale v16.0 migration note (force_load → immediate_hydration) is correct — documenting a migration path to a now-removed option is pure noise.

Minor observations (non-blocking)

1. configuration-deprecated.md still shows per-component overrides (e.g., react_component("MyComponent", immediate_hydration: false)). Since the option was removed in Remove immediate_hydration feature from codebase #2834, this example may mislead users into thinking per-component overrides still work. This is intentionally out of scope for this PR, but worth a follow-up issue to clarify or remove that example.

2. ruby-api-pro.md line 50 — the new sentence ("React on Rails Pro hydrates streamed components early … — no per-component toggle is exposed.") is run-on with "Options: same as react_component." as a single paragraph. A > **Note:** block or a line break would improve readability.

3. streaming-ssr.md migration timeline step 3 reads "Use React on Rails Pro", which sounds like a license recommendation rather than a migration action. Consider rephrasing to: "React on Rails Pro: early hydration is automatic, no additional configuration required."

Verdict

Approving. The core change is accurate and resolves real user confusion caused by stale option documentation.

Review comment triage (round 2)

Follow-up to my earlier triage. I (Claude Code) re-scanned the open review feedback and addressed two additional items raised in @claude[bot]'s detailed review:

Addressed in b32f1b5:

• docs/oss/configuration/configuration-deprecated.md — Removed the misleading react_component("MyComponent", immediate_hydration: false) per-component override example from the migration block. The per-component toggle was removed alongside the global option, so the example contradicted the new docs in this PR. Migration text now tells users to delete both config.immediate_hydration and any immediate_hydration: keys from react_component / stream_react_component calls.
• docs/pro/streaming-ssr.md:336 — Reworded Migration Timeline step 3 from "Use React on Rails Pro" to "Early Hydration (Pro): Pro hydrates components early for optimal Time to Interactive — no additional configuration needed". Pro is a prerequisite of the section, not a migration step, so the original wording read awkwardly.

Resolved (no code change needed):

• Inline thread on turbolinks.md:257 from @claude[bot] (the duplicate [!WARNING] callout nit) — the fix landed in f207a16. Replied on the thread and resolved it.

No action — rationale:

• @coderabbitai[bot] walkthrough + pre-merge checks — auto-generated summary; no actionable items.
• @claude[bot] earlier approval comment — already addressed in the prior triage round.
• @greptile-apps[bot] — 5/5 confidence, no findings.
• @coderabbitai[bot] / @greptile-apps[bot] acknowledgment replies — no further action expected.

PR is ready for merge review.

@justin808 — Round 2 triage looks thorough and the two additional fixes in b32f1b5 are both correct calls:

• configuration-deprecated.md: Removing the immediate_hydration: false per-component example was the right move — since the per-component toggle was removed alongside the global option in #2834, leaving that example would have directly contradicted the updated docs in this PR.
• streaming-ssr.md step 3: The reword to "Early Hydration (Pro): Pro hydrates components early for optimal Time to Interactive — no additional configuration needed" reads much better — Pro is a prerequisite for that entire section, not a migration step users need to take.

All outstanding review threads are now accounted for. PR is clean for merge. 🚀

Learnt from: CR
Repo: shakacode/react_on_rails PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-21T08:53:17.309Z
Learning: For small, focused PRs (roughly 5 files or fewer with one clear purpose): use at most one AI reviewer for inline comments, batch review fixes into one follow-up push, and verify language/runtime/library claims locally before making code changes in response to AI review

Learnt from: justin808
Repo: shakacode/react_on_rails PR: 0
File: :0-0
Timestamp: 2026-04-13T02:29:20.920Z
Learning: In `react_on_rails_pro/lib/react_on_rails_pro/engine.rb` and `react_on_rails/lib/react_on_rails/configuration.rb` (PR `#3094`): Do NOT reset `rendering_strategy` or `js_code_builder` inside `ReactOnRails.configure`. The Pro engine sets these exactly once during `after_initialize`; resetting them on reconfigure would silently drop Pro's NodeStrategy/ProJsCodeBuilder assignments. A proper reconfigure mechanism for these accessors is deferred to Step 3 of the strategy-pattern refactor (`#2905`).

Learnt from: justin808
Repo: shakacode/react_on_rails PR: 2651
File: docs/oss/introduction.md:47-47
Timestamp: 2026-03-26T02:20:12.940Z
Learning: In `docs/oss/introduction.md` (and related docs in the `shakacode/react_on_rails` repo), the link to `docs/oss/getting-started/comparison-with-alternatives.md` described as "a side-by-side matrix with benchmarks" is intentionally and accurately worded. The page includes actual benchmark sections (e.g., Vite vs Rspack benchmark tables), so the phrase "with benchmarks" should NOT be flagged as misleading in future reviews.

Learnt from: justin808
Repo: shakacode/react_on_rails PR: 2790
File: docs/oss/migrating/rsc-data-fetching.md:238-238
Timestamp: 2026-03-22T03:17:13.316Z
Learning: In `docs/oss/migrating/rsc-data-fetching.md` (React on Rails migration guide), the phrase "Rails fetches the data in the controller layer" is intentional and acceptable wording even when the ERB examples show inline ActiveRecord queries inside `stream_react_component`/`stream_react_component_with_async_props`. The inline queries are a teaching shortcut; "controller layer" is meant to convey that data fetching happens on the Rails side (not in React), not to mandate that queries must live in a controller action. Do not flag this phrasing as misleading in future reviews.

Learnt from: justin808
Repo: shakacode/react_on_rails PR: 2850
File: docs/oss/api-reference/rails-view-rendering-from-inline-javascript.md:0-0
Timestamp: 2026-03-26T07:01:43.653Z
Learning: In `packages/react-on-rails/src/ClientRenderer.ts`, the duplicate-render guard (which skips rendering if the DOM node is already connected/mounted) applies only to the automatic page-load rendering path. The public `ReactOnRails.render(...)` API routes through `packages/react-on-rails/src/base/client.ts` and calls `reactHydrateOrRender(...)` directly, without any deduplication guard. Therefore, repeated calls to the public `ReactOnRails.render(...)` API on the same DOM node (e.g., `#root`) WILL invoke React again — they are NOT deduplicated. Documentation stating this behavior is correct and should not be flagged.

Learnt from: CR
Repo: shakacode/react_on_rails PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-12T23:15:11.806Z
Learning: For small, focused PRs (5 files changed or fewer with one clear purpose): use at most one AI reviewer that leaves inline comments; additional AI tools should be summary-only or used manually

Learnt from: ihabadham
Repo: shakacode/react_on_rails PR: 2674
File: react_on_rails/lib/react_on_rails/doctor.rb:2325-2345
Timestamp: 2026-03-19T16:13:07.375Z
Learning: In `react_on_rails/lib/react_on_rails/doctor.rb`, `check_rsc_payload_route` and `check_rsc_procfile_watcher` filter commented lines (`/^\s*#/`) before checking for the target string, consistent with the `config_has_async_loading_strategy?` pattern. The doctor avoids a full Rails boot for resilience and uses file-content scanning instead of actual Rails route inspection. Remaining accepted limitations are dynamic/engine-mounted routes and routes loaded via the `draw` macro (uncommon, since the generator places `rsc_payload_route` directly in `config/routes.rb`).

Learnt from: justin808
Repo: shakacode/react_on_rails PR: 2530
File: react_on_rails_pro/lib/react_on_rails_pro/concerns/stream.rb:0-0
Timestamp: 2026-03-04T23:37:22.169Z
Learning: In `react_on_rails_pro/lib/react_on_rails_pro/concerns/stream.rb`, the `stream_view_containing_react_components` method intentionally does NOT set `Cache-Control: no-transform`. The PR `#2530` is an alternative fix for the Live streaming + compression middleware deadlock (issue `#2519`): instead of using `no-transform` to make compression middleware short-circuit, gzip is handled in-process via a custom `GzipOutputStream` class wrapping `Zlib::GzipWriter`. This keeps compression enabled for clients that support gzip while bypassing the middleware stack entirely. Do not suggest adding `Cache-Control: no-transform` to this method.

Learnt from: justin808
Repo: shakacode/react_on_rails PR: 2789
File: docs/pro/streaming-ssr.md:79-81
Timestamp: 2026-03-21T23:48:01.271Z
Learning: In React on Rails Pro, `stream_react_component` (defined in `react_on_rails_pro_helper.rb` around lines 127-129) forces `prerender: true` internally. The option is not configurable by callers, so documentation examples should NOT include `prerender: true` in `stream_react_component` invocations as it is misleading.

Learnt from: AbanoubGhadban
Repo: shakacode/react_on_rails PR: 1781
File: node_package/src/ClientSideRenderer.ts:82-95
Timestamp: 2025-09-15T21:24:48.207Z
Learning: In React on Rails, the force_load feature includes both explicit `data-force-load="true"` usage and the ability to hydrate components during the page loading state (`document.readyState === 'loading'`). Both capabilities require a Pro license, so the condition `!railsContext.rorPro && (isComponentForceLoaded || document.readyState === 'loading')` correctly gates both scenarios.

Learnt from: justin808
Repo: shakacode/react_on_rails PR: 2886
File: docs/sidebars.ts:9-251
Timestamp: 2026-03-29T08:38:50.670Z
Learning: In the `shakacode/react_on_rails` repository, `docs/sidebars.ts` uses sidebar doc IDs **without** an `oss/` prefix (e.g., `'api-reference/javascript-api'`, `'building-features/caching'`). Although OSS doc files are physically located at `docs/oss/...`, Docusaurus is configured to remap that path so those IDs resolve correctly without the prefix. Pro docs use the `pro/` prefix (e.g., `'pro/react-on-rails-pro'`). Do not suggest adding an `oss/` prefix to sidebar IDs in this repo.

Learnt from: justin808
Repo: shakacode/react_on_rails PR: 2610
File: docs/pro/react-server-components/create-without-ssr.md:13-22
Timestamp: 2026-03-24T21:38:26.825Z
Learning: In `docs/pro/react-server-components/create-without-ssr.md`, JS install instructions for React on Rails Pro should only install `react-on-rails-pro` (not `react-on-rails` separately), because the Pro package already includes the base package functionality. Use `--exact` (yarn/pnpm) or `--save-exact` (npm) flags to pin to an exact version for reproducibility.

Learnt from: CR
Repo: shakacode/react_on_rails PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-12T23:15:11.806Z
Learning: Applies to CHANGELOG.md : Changelog format: `[PR 1818](https://github.com/shakacode/react_on_rails/pull/1818) by [username](https://github.com/username)` (no hash before PR number)

Good triage summary. One remaining open thread to note: the ruby-api-pro.md:50 suggestion (splitting the run-on sentence about options and Pro hydration behavior into two separate statements) wasn't listed in your "Addressed" or "No action" categories — it appears unresolved. Worth a quick look before merge.

Everything else looks clean. The [!WARNING] fix, the migration timeline reword, and the configuration-deprecated.md cleanup are all confirmed addressed. LGTM pending that last item.

Review comment triage (round 3)

Follow-up to round 2. I (Claude Code) cleared the two remaining unresolved inline threads from @claude[bot]:

Addressed in 55e4490:

• docs/oss/api-reference/ruby-api-pro.md:50 — Split the run-on Options: same as react_component. React on Rails Pro hydrates... sentence into two ideas: a standalone options line and a > **Note (Pro):** callout for the early-hydration behavior. Improves scannability of the stream_react_component reference.

Resolved (no code change needed):

• docs/pro/streaming-ssr.md:336 thread from @claude[bot] — the "Use React on Rails Pro" → Early Hydration (Pro): Pro hydrates components early for optimal Time to Interactive — no additional configuration needed rewording already landed in b32f1b5. Same intent as the suggested wording, so replied on the thread and resolved it.

All inline review threads on this PR are now resolved. PR is ready for merge review.

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

Overall: Clean, well-scoped docs-only PR. The changes are accurate and the decision to preserve historical release-notes untouched is sound policy.

What's done well

• Correctly removes immediate_hydration from all current/active documentation (API reference, Turbo Streams guide, streaming SSR, Pro troubleshooting).
• The configuration-deprecated.md fix is the most impactful change: the old migration guidance told Pro users they could still use immediate_hydration: false per-component, which has been a no-op since Remove immediate_hydration feature from codebase #2834. That's now corrected.
• Fixes a malformed GitHub callout in turbolinks.md (> [!WARNING] > **... → properly split across lines) as a nice drive-by cleanup.
• The reframing from "Immediate Hydration" to "Early Hydration (Pro)" throughout streaming-ssr.md is clearer and matches how the feature actually behaves.

One issue to address

docs/oss/upgrading/release-notes/16.2.0.md:279 (intentionally left out of scope per PR description) contains:

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.

The last sentence actively contradicts what this PR establishes — per-component immediate_hydration: keys are no-ops since #2834, and configuration-deprecated.md (updated in this PR) now explicitly says to delete them. Unlike the rest of 16.2.0.md (historical code examples in their original context), this is live migration guidance that will send users chasing an option that no longer exists. I've left an inline comment on that line.

Verification

The PR test-plan grep passes: no live immediate_hydration references remain outside of intentionally preserved files (upgrade guides, release notes, deprecated-config doc).

Review comment triage (round 4)

Follow-up to round 3. I (Claude Code) triaged the latest @claude[bot] review, which flagged one remaining piece of live migration guidance inside an otherwise historical release-notes file.

Addressed:

• docs/oss/upgrading/release-notes/16.2.0.md:279 — dropped the trailing "Use component-level overrides if needed." from the Immediate Hydration Config Warning troubleshooting entry. The bot's distinction was right: per-component immediate_hydration: keys have been no-ops since Remove immediate_hydration feature from codebase #2834, and configuration-deprecated.md (updated in this PR) now instructs users to delete them, so the release-notes sentence was sending readers after a phantom option. Fixed in b9a328d. The rest of 16.2.0.md remains untouched — it's historical code in context, not active migration guidance.

No open threads. All five inline review threads from earlier rounds are still resolved. No new inline comments were posted in this review, so nothing to reply to or resolve.

Code Review

Overall: This is a clean, well-scoped docs-only cleanup. The prose reframing is accurate and the stale code examples are correctly removed. A couple of issues worth addressing:

Issue 1: PR description lists configuration-deprecated.md as "intentionally left alone" — but it was modified

The description says:

Per the issue, release notes and deprecation docs still correctly reference immediate_hydration as a historical/deprecated option: … docs/oss/configuration/configuration-deprecated.md

But the diff clearly modifies that file (removes the Pro per-component disable example, rewrites the migration note). This is actually the right change — just the PR description is inaccurate about it.

Issue 2: Internal contradiction between 16.2.0.md and updated configuration-deprecated.md

docs/oss/upgrading/release-notes/16.2.0.md (intentionally left unchanged) still contains:

Component-level overrides still work:

<%= react_component("MyComponent", props, immediate_hydration: false) %>
<%= redux_store("MyStore", props: store_props, immediate_hydration: true) %>

But configuration-deprecated.md (modified by this PR) now states:

Remove any immediate_hydration: keys passed to react_component / stream_react_component — both are no-ops and can be safely deleted.

A user upgrading from v16 will read the 16.2.0 release notes first and learn that per-component overrides work, then hit the deprecated config page and find they don't. Since the option was removed in v17.0, the 16.2.0 release notes section could use a small callout:

> **Note (v17+):** Per-component `immediate_hydration` overrides were also removed in v17.0. See [Deprecated Configuration](../../configuration/configuration-deprecated.md).

This preserves the historical accuracy of the 16.2.0 notes while helping readers on an upgrade path.

Minor positives worth calling out

• The > [!WARNING] block formatting fix (removing the stray > that preceded the bold title on the same line) is a correct markdown fix.
• Removing the dead link to the v16.0 release notes from turbolinks.md is good hygiene.
• The test plan grep command is a solid verification approach and its claim checks out.

Code Review

Overall: Clean, well-scoped documentation-only PR. The immediate_hydration option was genuinely removed in v16.6.0 (confirmed in CHANGELOG), and keeping stale per-component toggle examples in live docs would mislead users. The reframing to "Early Hydration (Pro)" is accurate and reads well.

What's correct

• Version fix in configuration-deprecated.md: changing "REMOVED in v17.0" → "REMOVED in v16.6.0" matches the CHANGELOG entry for v16.6.0 exactly.
• Removal of the per-component immediate_hydration: false example from streaming-ssr.md — that feature is gone.
• Removal of immediate_hydration: true from the Turbo Streams ERB example in turbolinks.md — previously the example would silently do nothing for OSS users and confusingly appear optional for Pro users.
• Warning-box formatting fix in turbolinks.md (> [!WARNING] > → > [!WARNING] on its own line) — the original was broken GitHub-flavored Markdown.
• Preserving historical accuracy in 16.0.0.md — those release notes correctly document what was true at that version.

Issues found

1. configuration-deprecated.md — "no-op" description is imprecise for stream_react_component (inline comment left)
   The CHANGELOG says react_component silently ignores the key but stream_react_component actively logs a deprecation warning. Calling both "no-ops" may confuse users who see warnings in their logs after following this migration guide.

2. 16.2.0.md is listed as "intentionally left alone" but is modified (inline comment left)
   The change itself is correct (removing "Use component-level overrides if needed"), but the PR description misclassifies the file. Needs a description update only.

3. 16.2.0.md still has a "Component-level overrides still work" code block — fine because release notes should reflect what was true at that version, but worth a reviewer sanity-check that the section won't be mistaken for current guidance.

Minor observations

• The ruby-api-pro.md blockquote note reads well and is accurate.
• The turbolinks prose changes are clear improvements; "early hydration is automatic for Pro users" is more actionable than the old option-name-dropping style.

No runtime behavior changes. Two small fixes needed before merge (see inline comments), both are doc-only tweaks.

Review comment triage (round 5)

Follow-up to round 4. I (Claude Code) triaged the latest @claude[bot] review plus a user-flagged version bug on line 11 of docs/oss/configuration/configuration-deprecated.md.

Addressed:

• docs/oss/configuration/configuration-deprecated.md:11 — corrected **Status:** ⚠️ REMOVED in v17.0 to v16.6.0. immediate_hydration was actually removed in v16.6.0 (released 2026-04-09 per CHANGELOG); v17.0 has not been released. Fixed in 3357db9.
• PR description — updated to reflect what the PR actually modifies. Moved docs/oss/configuration/configuration-deprecated.md and docs/oss/upgrading/release-notes/16.2.0.md out of "Files intentionally left alone" (both were modified during earlier rounds) and expanded the turbolinks.md entry to include the [!WARNING] alert fix and the ruby-api-pro.md entry to mention the options/hydration note split. This addresses claude[bot]'s "Issue 1" in the latest review.

Declined (with reply and thread resolved):

• Thread on configuration-deprecated.md:15 — claude[bot] suggested adding a parenthetical cross-reference about v16.2/v17.0 timeline to the migration step. Not applied: the suggestion's version number was wrong (v17.0), and the preferred approach is to keep the 16.2.0 release-notes section as accurate historical context rather than layering cross-references onto current migration guidance. Replied and resolved.

Considered and declined (no thread to resolve):

• claude[bot]'s "Issue 2" (add a > **Note (v17+):** Per-component overrides were also removed... callout inside the 16.2.0 release notes' "Component-level overrides still work" section) — same reasoning as above: 16.2.0 release notes are preserved as a historical snapshot accurate to that release; v17 doesn't exist, and the configuration-deprecated.md page is the canonical home for current-state deprecation guidance. Readers on an upgrade path will see the deprecation entry through the sidebar and CHANGELOG.

No open threads. The last unresolved thread is now resolved.