docs(start): compare deferred hydration to React selective hydration by tannerlinsley · Pull Request #7442 · TanStack/router

tannerlinsley · 2026-05-20T01:35:16Z

Summary

Adds a "Comparison To React Selective Hydration" section to the deferred hydration docs, framing selective hydration as a scheduler for inevitable work and deferred hydration as a gate that controls whether and when that work happens.
Mirrors the section in the Solid docs via ref/replace frontmatter (renamed to "Solid Streaming Hydration", with click-driven reprioritization swapped for resource-driven streaming).

Test plan

prettier --check passes on both files
Verify the new section renders correctly on the docs site

Summary by CodeRabbit

Documentation
- Added comparison section in React guide explaining how TanStack Start deferred hydration differs from React selective hydration.
- Updated Solid framework documentation with clarified deferred hydration behavior using Solid-specific terminology.
- Enhanced guidance on boundary hydration handling and framework-specific considerations.

Adds a short comparison section answering the common question about how TanStack Start's deferred hydration relates to React 18's selective hydration. The framing: selective hydration controls the order of inevitable hydration work; deferred hydration controls whether and when that work happens at all.

coderabbitai · 2026-05-20T01:35:36Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 940549a6-9ab4-4034-b657-a53341f2d307

📥 Commits

Reviewing files that changed from the base of the PR and between ac4b43f and 4d99ab0.

📒 Files selected for processing (2)

docs/start/framework/react/guide/deferred-hydration.md
docs/start/framework/solid/guide/deferred-hydration.md

📝 Walkthrough

Walkthrough

This PR updates deferred hydration documentation for React and Solid frameworks in TanStack Start. The React guide adds a new comparison section explaining how deferred hydration differs from React selective hydration in boundary ordering and code-splitting. The Solid guide refines existing comparison text to use Solid terminology, clarifies deferred hydration mechanics, and improves guidance on extracting JSX with hooks.

Changes

Deferred Hydration Framework Guides

Layer / File(s)	Summary
React selective hydration comparison `docs/start/framework/react/guide/deferred-hydration.md`	New section compares TanStack Start deferred hydration with React selective hydration, detailing differences in hydration queue behavior, the role of `Hydrate when` conditions with default code-splitting, and how hydration scheduling resumes with nested `<Suspense>` boundaries.
Solid hydration comparison and guidance refinements `docs/start/framework/solid/guide/deferred-hydration.md`	Comparison text updated from React-centric to Solid/streaming hydration framing; deferred hydration explanation clarified for Solid including DOM clearing and subtree mounting; guidance refined for JSX extraction containing hook calls.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

TanStack/router#7438: Overlapping documentation updates to the same React and Solid deferred hydration guide files, adding alternative "comparison" sections and wording.

Suggested labels

documentation

🐰 Hydration guides now shine with clarity bright,
React and Solid side by side, explained just right,
Boundaries deferred, suspense in a dance,
Each framework's heartbeat gets its chance! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and specifically identifies the main change: adding a comparison section to deferred hydration documentation explaining how it relates to React selective hydration.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch taren/peaceful-curran-c8e01b

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

nx-cloud · 2026-05-20T01:35:52Z

View your CI Pipeline Execution ↗ for commit 4d99ab0

Command	Status	Duration	Result
`nx run-many --target=build --exclude=examples/*...`	✅ Succeeded	2m 21s	View ↗
`nx affected --targets=test:eslint,test:unit,tes...`	✅ Succeeded	<1s	View ↗

☁️ Nx Cloud last updated this comment at 2026-05-20 01:38:36 UTC

github-actions · 2026-05-20T01:36:06Z

🚀 Changeset Version Preview

8 package(s) bumped directly, 16 bumped as dependents.

🟨 Minor bumps

Package	Version	Reason
`@tanstack/react-start-client`	1.167.4 → 1.168.0	Changeset
`@tanstack/solid-start-client`	1.167.4 → 1.168.0	Changeset
`@tanstack/start-client-core`	1.169.4 → 1.170.0	Changeset
`@tanstack/start-plugin-core`	1.170.6 → 1.171.0	Changeset
`@tanstack/start-server-core`	1.168.4 → 1.169.0	Changeset

🟩 Patch bumps

Package	Version	Reason
`@tanstack/router-core`	1.171.2 → 1.171.3	Changeset
`@tanstack/router-plugin`	1.168.6 → 1.168.7	Changeset
`@tanstack/router-utils`	1.162.0 → 1.162.1	Changeset
`@tanstack/react-router`	1.170.4 → 1.170.5	Dependent
`@tanstack/react-start`	1.168.6 → 1.168.7	Dependent
`@tanstack/react-start-rsc`	0.1.6 → 0.1.7	Dependent
`@tanstack/react-start-server`	1.167.4 → 1.167.5	Dependent
`@tanstack/router-cli`	1.167.5 → 1.167.6	Dependent
`@tanstack/router-generator`	1.167.5 → 1.167.6	Dependent
`@tanstack/router-vite-plugin`	1.167.6 → 1.167.7	Dependent
`@tanstack/solid-router`	1.170.4 → 1.170.5	Dependent
`@tanstack/solid-start`	1.168.6 → 1.168.7	Dependent
`@tanstack/solid-start-server`	1.167.4 → 1.167.5	Dependent
`@tanstack/start-static-server-functions`	1.167.4 → 1.167.5	Dependent
`@tanstack/start-storage-context`	1.167.4 → 1.167.5	Dependent
`@tanstack/vue-router`	1.170.4 → 1.170.5	Dependent
`@tanstack/vue-start`	1.168.6 → 1.168.7	Dependent
`@tanstack/vue-start-client`	1.167.4 → 1.167.5	Dependent
`@tanstack/vue-start-server`	1.167.4 → 1.167.5	Dependent

pkg-pr-new · 2026-05-20T01:39:57Z

More templates

@tanstack/arktype-adapter

npm i https://pkg.pr.new/@tanstack/arktype-adapter@7442

@tanstack/eslint-plugin-router

npm i https://pkg.pr.new/@tanstack/eslint-plugin-router@7442

@tanstack/eslint-plugin-start

npm i https://pkg.pr.new/@tanstack/eslint-plugin-start@7442

@tanstack/history

npm i https://pkg.pr.new/@tanstack/history@7442

@tanstack/nitro-v2-vite-plugin

npm i https://pkg.pr.new/@tanstack/nitro-v2-vite-plugin@7442

@tanstack/react-router

npm i https://pkg.pr.new/@tanstack/react-router@7442

@tanstack/react-router-devtools

npm i https://pkg.pr.new/@tanstack/react-router-devtools@7442

@tanstack/react-router-ssr-query

npm i https://pkg.pr.new/@tanstack/react-router-ssr-query@7442

@tanstack/react-start

npm i https://pkg.pr.new/@tanstack/react-start@7442

@tanstack/react-start-client

npm i https://pkg.pr.new/@tanstack/react-start-client@7442

@tanstack/react-start-rsc

npm i https://pkg.pr.new/@tanstack/react-start-rsc@7442

@tanstack/react-start-server

npm i https://pkg.pr.new/@tanstack/react-start-server@7442

@tanstack/router-cli

npm i https://pkg.pr.new/@tanstack/router-cli@7442

@tanstack/router-core

npm i https://pkg.pr.new/@tanstack/router-core@7442

@tanstack/router-devtools

npm i https://pkg.pr.new/@tanstack/router-devtools@7442

@tanstack/router-devtools-core

npm i https://pkg.pr.new/@tanstack/router-devtools-core@7442

@tanstack/router-generator

npm i https://pkg.pr.new/@tanstack/router-generator@7442

@tanstack/router-plugin

npm i https://pkg.pr.new/@tanstack/router-plugin@7442

@tanstack/router-ssr-query-core

npm i https://pkg.pr.new/@tanstack/router-ssr-query-core@7442

@tanstack/router-utils

npm i https://pkg.pr.new/@tanstack/router-utils@7442

@tanstack/router-vite-plugin

npm i https://pkg.pr.new/@tanstack/router-vite-plugin@7442

@tanstack/solid-router

npm i https://pkg.pr.new/@tanstack/solid-router@7442

@tanstack/solid-router-devtools

npm i https://pkg.pr.new/@tanstack/solid-router-devtools@7442

@tanstack/solid-router-ssr-query

npm i https://pkg.pr.new/@tanstack/solid-router-ssr-query@7442

@tanstack/solid-start

npm i https://pkg.pr.new/@tanstack/solid-start@7442

@tanstack/solid-start-client

npm i https://pkg.pr.new/@tanstack/solid-start-client@7442

@tanstack/solid-start-server

npm i https://pkg.pr.new/@tanstack/solid-start-server@7442

@tanstack/start-client-core

npm i https://pkg.pr.new/@tanstack/start-client-core@7442

@tanstack/start-fn-stubs

npm i https://pkg.pr.new/@tanstack/start-fn-stubs@7442

@tanstack/start-plugin-core

npm i https://pkg.pr.new/@tanstack/start-plugin-core@7442

@tanstack/start-server-core

npm i https://pkg.pr.new/@tanstack/start-server-core@7442

@tanstack/start-static-server-functions

npm i https://pkg.pr.new/@tanstack/start-static-server-functions@7442

@tanstack/start-storage-context

npm i https://pkg.pr.new/@tanstack/start-storage-context@7442

@tanstack/valibot-adapter

npm i https://pkg.pr.new/@tanstack/valibot-adapter@7442

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/@tanstack/virtual-file-routes@7442

@tanstack/vue-router

npm i https://pkg.pr.new/@tanstack/vue-router@7442

@tanstack/vue-router-devtools

npm i https://pkg.pr.new/@tanstack/vue-router-devtools@7442

@tanstack/vue-router-ssr-query

npm i https://pkg.pr.new/@tanstack/vue-router-ssr-query@7442

@tanstack/vue-start

npm i https://pkg.pr.new/@tanstack/vue-start@7442

@tanstack/vue-start-client

npm i https://pkg.pr.new/@tanstack/vue-start-client@7442

@tanstack/vue-start-server

npm i https://pkg.pr.new/@tanstack/vue-start-server@7442

@tanstack/zod-adapter

npm i https://pkg.pr.new/@tanstack/zod-adapter@7442

commit: 4d99ab0

github-actions Bot added the documentation Everything documentation related label May 20, 2026

tannerlinsley merged commit 0bfb7ef into main May 20, 2026
10 checks passed

tannerlinsley deleted the taren/peaceful-curran-c8e01b branch May 20, 2026 01:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(start): compare deferred hydration to React selective hydration#7442

docs(start): compare deferred hydration to React selective hydration#7442
tannerlinsley merged 1 commit into
mainfrom
taren/peaceful-curran-c8e01b

tannerlinsley commented May 20, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented May 20, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Uh oh!

nx-cloud Bot commented May 20, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 20, 2026

Uh oh!

pkg-pr-new Bot commented May 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

tannerlinsley commented May 20, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Uh oh!

nx-cloud Bot commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented May 20, 2026

🚀 Changeset Version Preview

🟨 Minor bumps

🟩 Patch bumps

Uh oh!

pkg-pr-new Bot commented May 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

tannerlinsley commented May 20, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented May 20, 2026 •

edited

Loading

nx-cloud Bot commented May 20, 2026 •

edited

Loading