Skip to content

Commit 4d99ab0

Browse files
committed
docs(start): compare deferred hydration to React selective hydration
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.
1 parent ac4b43f commit 4d99ab0

2 files changed

Lines changed: 33 additions & 0 deletions

File tree

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

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,35 @@ Same trigger vocabulary, different substrate: Astro composes runtimes, Start
104104
schedules one. That is why Start gets `interaction()`, `condition()`, and intent
105105
bubbling, and why Astro gets multi-framework.
106106

107+
## Comparison To React Selective Hydration
108+
109+
React's selective hydration controls the order in which server-rendered
110+
boundaries hydrate. Deferred hydration controls whether and when each
111+
boundary hydrates at all.
112+
113+
When React hydrates a streaming SSR page, every server-rendered
114+
`<Suspense>` boundary will eventually hydrate. Selective hydration just
115+
decides the order: each boundary hydrates as soon as its code arrives,
116+
and React jumps a boundary to the front of the queue if the user clicks
117+
inside it. The work is fixed by what the server rendered; React
118+
schedules it to feel responsive.
119+
120+
Deferred hydration changes what is in the queue in the first place. A
121+
`Hydrate` boundary names a condition — `visible()`, `idle()`,
122+
`interaction()`, `media()`, `condition()`, or `never()` — and the
123+
boundary stays as static server HTML until that condition fires. By
124+
default the child JavaScript also moves into a separate chunk that the
125+
browser does not download until the boundary is about to hydrate. If the
126+
condition never fires, the boundary never hydrates and its code is never
127+
fetched.
128+
129+
The two compose. A `Hydrate` boundary decides whether and when React
130+
starts hydrating a subtree; once it opens, anything inside it (including
131+
`<Suspense>` boundaries) flows back into React's normal hydration
132+
scheduler. Use `<Suspense>` when hydration must happen and you want React
133+
to prioritize it well. Use `Hydrate` when hydration might not need to
134+
happen at all.
135+
107136
## The Three Decisions
108137

109138
Each `Hydrate` boundary has three performance decisions:

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@ replace:
44
'@tanstack/react-start': '@tanstack/solid-start'
55
'React handlers': 'Solid handlers'
66
'one React tree': 'one Solid tree'
7+
'Comparison To React Selective Hydration': 'Comparison To Solid Streaming Hydration'
8+
"React's selective hydration controls the order in which server-rendered boundaries hydrate. Deferred hydration controls whether and when each boundary hydrates at all.": "Solid's streaming hydration controls the order in which server-rendered boundaries hydrate. Deferred hydration controls whether and when each boundary hydrates at all."
9+
'When React hydrates a streaming SSR page, every server-rendered `<Suspense>` boundary will eventually hydrate. Selective hydration just decides the order: each boundary hydrates as soon as its code arrives, and React jumps a boundary to the front of the queue if the user clicks inside it. The work is fixed by what the server rendered; React schedules it to feel responsive.': 'When Solid hydrates a streaming SSR page, every server-rendered `<Suspense>` boundary will eventually hydrate. Streaming hydration just decides the order: each boundary hydrates as its resources resolve and stream from the server. The work is fixed by what the server rendered; Solid streams it to feel responsive.'
10+
"The two compose. A `Hydrate` boundary decides whether and when React starts hydrating a subtree; once it opens, anything inside it (including `<Suspense>` boundaries) flows back into React's normal hydration scheduler. Use `<Suspense>` when hydration must happen and you want React to prioritize it well. Use `Hydrate` when hydration might not need to happen at all.": "The two compose. A `Hydrate` boundary decides whether and when Solid starts hydrating a subtree; once it opens, anything inside it (including `<Suspense>` boundaries) flows back into Solid's normal hydration scheduler. Use `<Suspense>` when hydration must happen and you want Solid to prioritize it well. Use `Hydrate` when hydration might not need to happen at all."
711
'ReactNode': 'JSX.Element'
812
"Deferred hydration is a performance hint for React's initial hydration work. React may hydrate a deferred boundary earlier than its strategy would normally allow if state, props, context, or store updates outside the boundary require React to reconcile inside it before the gate opens. This preserves correctness and avoids showing stale server HTML after the surrounding app has changed.": "Deferred hydration is a performance hint for Solid's initial hydration work. Once a boundary gate opens, TanStack Start clears the preserved server DOM inside the marker and mounts the live Solid subtree in its place."
913
'Hook calls directly inside extracted JSX': 'Render-time `use*` calls directly inside extracted JSX'

0 commit comments

Comments
 (0)