Skip to content

Commit ac4b43f

Browse files
docs(start): compare deferred hydration to Astro islands (#7438)
Adds a short mental-model section answering the common question about how TanStack Start's deferred hydration relates to Astro islands.
1 parent 60ad69c commit ac4b43f

2 files changed

Lines changed: 16 additions & 0 deletions

File tree

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,21 @@ Poor candidates are parts of the page users may need immediately:
8989
Measure each boundary. A useful boundary reduces startup JavaScript or hydration
9090
work without making expected interactions feel late.
9191

92+
## Comparison To Astro Islands
93+
94+
Astro starts static and asks "what should come alive?" Each answer is an
95+
isolated framework root dropped into HTML. Islands are independent runtimes
96+
sharing a DOM.
97+
98+
TanStack Start starts fully interactive and asks "what can wait?" The whole
99+
document hydrates as one React tree by default; `Hydrate` boundaries are gates
100+
inside that tree. Context, state, and events flow through normally, and
101+
hydration is parent-first.
102+
103+
Same trigger vocabulary, different substrate: Astro composes runtimes, Start
104+
schedules one. That is why Start gets `interaction()`, `condition()`, and intent
105+
bubbling, and why Astro gets multi-framework.
106+
92107
## The Three Decisions
93108

94109
Each `Hydrate` boundary has three performance decisions:

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ ref: docs/start/framework/react/guide/deferred-hydration.md
33
replace:
44
'@tanstack/react-start': '@tanstack/solid-start'
55
'React handlers': 'Solid handlers'
6+
'one React tree': 'one Solid tree'
67
'ReactNode': 'JSX.Element'
78
"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."
89
'Hook calls directly inside extracted JSX': 'Render-time `use*` calls directly inside extracted JSX'

0 commit comments

Comments
 (0)