Open History to see the last commit
1---
2id: deferred-hydration
3title: Deferred Hydration
4---
5β
6> Deferred hydration is experimental
7β
8On an initial page load, TanStack Start server-renders your page so the browser
9can show useful HTML quickly. Hydration is the client-side work that turns that
10initial HTML document into an interactive app. It loads and executes JavaScript,
11runs components, attaches event handlers, and reconnects the existing DOM to
12React.
13β
14Deferred hydration applies to this initial document hydration work. After the
15app is already running, subsequent client-side navigations render through the
16client app; there is no initial server HTML for TanStack Start to preserve.
17β
18By default, TanStack Start hydrates the full document. That is usually the
19simplest and safest behavior, but large pages can spend meaningful startup time
20loading JavaScript and hydrating parts of the page that the user may not need
21right away.
22β
23Deferred hydration lets you mark selected parts of a page as "not interactive
24yet". The server HTML remains in the document, but TanStack Start waits to
25hydrate that boundary until a strategy says it is time. By default, the compiler
26also moves the boundary children into a separate JavaScript chunk so the browser
27can delay loading that code too.
28β
29Use deferred hydration when a part of the page should be visible, styled, and
30indexable immediately, but does not need to be interactive immediately.
31β
32## Add A Deferred Boundary
33β
34Use `Hydrate` with a strategy from `@tanstack/react-start/hydration`:
35β
36```tsx
37import { Hydrate } from '@tanstack/react-start'
38import { visible } from '@tanstack/react-start/hydration'
39β
40export function ProductPage() {
41 return (
42 <Hydrate when={visible({ rootMargin: '400px' })}>
43 <Reviews />
44 </Hydrate>
45 )
46}
47```
48β
49On the initial server response, `Reviews` is still rendered to HTML. During the
50initial client hydration pass, that HTML is preserved but the `Reviews` React
51tree does not hydrate yet. When the boundary comes within `400px` of the
52viewport, TanStack Start loads the deferred child chunk and hydrates the
53boundary.
54β
55`Hydrate` only preserves server HTML that exists in the initial document. If the
56same boundary first mounts later, for example after client-side navigation,
57there is no server HTML to preserve, so it renders normally on the client.
58β
59## Choose What To Defer
60β
61The right boundary depends on your page, your product priorities, and real user
62behavior. TanStack Start cannot know which parts of your page are safe to delay.
63β
64Good candidates are usually SSR content that is not needed for immediate
65interaction:
66β
67- Below-the-fold reviews, comments, product details, related content, or long
68 marketing sections.
69- Rich widgets such as maps, charts, carousels, video players, editors, or
70 embeds.
71- Panels that are activated by intent, such as filters, preview panes, or
72 contextual tools.
73- UI that only matters for a matching media query.
74- Static server-rendered content that should not hydrate on the initial
75 document.
76β
77Poor candidates are parts of the page users may need immediately:
78β
79- Primary navigation, route chrome, search boxes, and account controls.
80- Above-the-fold forms, add-to-cart buttons, checkout actions, or consent
81 controls.
82- The interactive part of the LCP or hero area when users may click it
83 immediately.
84- Accessibility-critical controls that must be keyboard-ready as soon as the
85 page appears.
86- Components whose props, context, or shared state are expected to update
87 immediately after app startup.
88β
89Measure each boundary. A useful boundary reduces startup JavaScript or hydration
90work without making expected interactions feel late.
91β
92## Comparison To Astro Islands
93β
94Astro starts static and asks "what should come alive?" Each answer is an
95isolated framework root dropped into HTML. Islands are independent runtimes
96sharing a DOM.
97β
98TanStack Start starts fully interactive and asks "what can wait?" The whole
99document hydrates as one React tree by default; `Hydrate` boundaries are gates
100inside that tree. Context, state, and events flow through normally, and
101hydration is parent-first.
102β
103Same trigger vocabulary, different substrate: Astro composes runtimes, Start
104schedules one. That is why Start gets `interaction()`, `condition()`, and intent
105bubbling, and why Astro gets multi-framework.
106β
107## Comparison To React Selective Hydration
108β
109React's selective hydration controls the order in which server-rendered
110boundaries hydrate. Deferred hydration controls whether and when each
111boundary hydrates at all.
112β
113When React hydrates a streaming SSR page, every server-rendered
114`<Suspense>` boundary will eventually hydrate. Selective hydration just
115decides the order: each boundary hydrates as soon as its code arrives,
116and React jumps a boundary to the front of the queue if the user clicks
117inside it. The work is fixed by what the server rendered; React
118schedules it to feel responsive.
119β
120Deferred 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
123boundary stays as static server HTML until that condition fires. By
124default the child JavaScript also moves into a separate chunk that the
125browser does not download until the boundary is about to hydrate. If the
126condition never fires, the boundary never hydrates and its code is never
127fetched.
128β
129The two compose. A `Hydrate` boundary decides whether and when React
130starts hydrating a subtree; once it opens, anything inside it (including
131`<Suspense>` boundaries) flows back into React's normal hydration
132scheduler. Use `<Suspense>` when hydration must happen and you want React
133to prioritize it well. Use `Hydrate` when hydration might not need to
134happen at all.
135β
136## The Three Decisions
137β
138Each `Hydrate` boundary has three performance decisions:
139β
140| Decision | Option | What it controls |
141| ----------- | ---------- | ------------------------------------------------------------------ |
142| Hydration | `when` | When the preserved server HTML becomes interactive. |
143| Code split | `split` | Whether the children move into a generated deferred child chunk. |
144| Preparation | `prefetch` | Whether work starts before the `when` strategy hydrates the child. |
145β
146### `when`: decide when the boundary hydrates
147β
148`when` is required. Pass a strategy object for the common case:
149β
150```tsx
151<Hydrate when={visible()}>
152 <Reviews />
153</Hydrate>
154```
155β
156Pass a function when the decision needs browser-only information:
157β
158```tsx
159import { Hydrate } from '@tanstack/react-start'
160import { interaction, visible } from '@tanstack/react-start/hydration'
161β
162export function RecommendationsBoundary() {
163 return (
164 <Hydrate
165 when={() =>
166 navigator.connection?.saveData
167 ? interaction({ events: 'click' })
168 : visible()
169 }
170 >
171 <Recommendations />
172 </Hydrate>
173 )
174}
175```
176β
177The function form is evaluated only on the client and must synchronously return
178a strategy. Use `never()` when you intentionally want the initial server HTML to
179stay static.
180β
181### `split`: decide whether to create a separate child chunk
182β
183By default, `Hydrate` splits the children into a generated child chunk:
184β
185```tsx
186<Hydrate when={visible()}>
187 <HeavyWidget />
188</Hydrate>
189```
190β
191This delays both hydration work and child JavaScript loading.
192β
193Set `split={false}` when the child code is small or already needed elsewhere,
194and you only want to delay hydration work:
195β
196```tsx
197import { Hydrate } from '@tanstack/react-start'
198import { idle } from '@tanstack/react-start/hydration'
199β
200export function SmallWidgetBoundary() {
201 return (
202 <Hydrate when={idle()} split={false}>
203 <SmallWidget />
204 </Hydrate>
205 )
206}
207```
208β
209### `prefetch`: decide whether to start loading before hydration
210β
211`prefetch` starts loading before the boundary hydrates. It has two forms:
212β
213| Form | Example | Use it for |
214| ------------------- | ----------------------------------- | -------------------------------------------------------------- |
215| Prefetch strategy | `prefetch={idle()}` | Preloading the generated child chunk before hydration. |
216| Procedural prefetch | `prefetch={async (ctx) => { ... }}` | Preloading the child chunk plus data or other async resources. |
217β
218Both forms start work early, but they do not change when the boundary becomes
219interactive. That is still controlled by `when`.
220β
221A prefetch strategy is the small, declarative form:
222β
223```tsx
224import { idle, interaction, visible } from '@tanstack/react-start/hydration'
225β
226<Hydrate when={interaction()} prefetch={idle()}>
227 <ProductRecommendations />
228</Hydrate>
229β
230<Hydrate
231 when={interaction()}
232 prefetch={visible({ rootMargin: '1200px' })}
233>
234 <RelatedProducts />
235</Hydrate>
236```
237β
238Strategy-form `prefetch` downloads the generated child chunk before the boundary
239hydrates. This can make the later hydration trigger feel faster, because the
240browser may already have the chunk by the time `when` resolves. Generated child
241chunks only exist when `split` is enabled, so TypeScript rejects strategy-form
242`prefetch` when `split={false}`.
243β
244Use procedural prefetch when you need custom work:
245β
246```tsx
247import { noop, useQueryClient } from '@tanstack/react-query'
248import { Hydrate } from '@tanstack/react-start'
249import { visible } from '@tanstack/react-start/hydration'
250β
251function DeferredReviews() {
252 const queryClient = useQueryClient()
253β
254 return (
255 <Hydrate
256 when={visible()}
257 prefetch={async ({ preload }) => {
258 await Promise.all([
259 preload(),
260 queryClient.query(reviewsQueryOptions).catch(noop),
261 ])
262 }}
263 >
264 <Reviews />
265 </Hydrate>
266 )
267}
268```
269β
270Procedural prefetch also works with `split={false}`. In that case, `preload()`
271is a resolved no-op, but the function can still prepare data or other
272resources.
273β
274## Common Recipes
275β
276### Hydrate below-the-fold SSR content
277β
278```tsx
279import { Hydrate } from '@tanstack/react-start'
280import { visible } from '@tanstack/react-start/hydration'
281β
282export function ProductPage() {
283 return (
284 <>
285 <ProductHero />
286 <BuyBox />
287β
288 <Hydrate when={visible({ rootMargin: '800px' })}>
289 <Reviews />
290 </Hydrate>
291 </>
292 )
293}
294```
295β
296Use a positive `rootMargin` when the boundary should hydrate before it actually
297enters the viewport.
298β
299### Download the child chunk before it is needed
300β
301```tsx
302import { Hydrate } from '@tanstack/react-start'
303import { idle, visible } from '@tanstack/react-start/hydration'
304β
305export function ReviewsBoundary() {
306 return (
307 <Hydrate when={visible({ rootMargin: '200px' })} prefetch={idle()}>
308 <Reviews />
309 </Hydrate>
310 )
311}
312```
313β
314This keeps the boundary non-interactive until it is close to the viewport, but
315starts loading the child chunk during idle time.
316β
317### Keep a widget cold until user intent
318β
319```tsx
320import { Hydrate } from '@tanstack/react-start'
321import { interaction, visible } from '@tanstack/react-start/hydration'
322β
323export function RecommendationsBoundary() {
324 return (
325 <Hydrate
326 when={interaction({ events: ['focusin', 'click'] })}
327 prefetch={visible({ rootMargin: '1200px' })}
328 >
329 <RecommendationCarousel />
330 </Hydrate>
331 )
332}
333```
334β
335This is useful for expensive controls that are visible or nearby, but only
336matter when the user reaches for them.
337β
338### Delay hydration without code splitting
339β
340```tsx
341import { Hydrate } from '@tanstack/react-start'
342import { idle } from '@tanstack/react-start/hydration'
343β
344export function BadgeBoundary() {
345 return (
346 <Hydrate when={idle()} split={false}>
347 <SmallPersonalizedBadge />
348 </Hydrate>
349 )
350}
351```
352β
353Use this when the JavaScript is already part of the startup bundle or when a
354separate child chunk would not be worth it.
355β
356### Keep initial SSR HTML static
357β
358```tsx
359import { Hydrate } from '@tanstack/react-start'
360import { never } from '@tanstack/react-start/hydration'
361β
362export function MarketingPage() {
363 return (
364 <Hydrate when={never()}>
365 <StaticTrustBadges />
366 </Hydrate>
367 )
368}
369```
370β
371`never()` preserves the existing server HTML and does not hydrate the boundary
372during initial document hydration. If the same boundary mounts later during
373client-side navigation, it renders normally because there is no initial server
374HTML to preserve. `never()` cannot be used as a prefetch strategy.
375β
376### Reuse Hydrate props
377β
378Use `HydrateOptions` for reusable objects that you spread into `Hydrate`:
379β
380```tsx
381import { Hydrate } from '@tanstack/react-start'
382import type { HydrateOptions } from '@tanstack/react-start'
383import { visible } from '@tanstack/react-start/hydration'
384β
385const belowFoldProps = {
386 when: () => visible({ rootMargin: '800px' }),
387} satisfies HydrateOptions
388β
389export function Page() {
390 return (
391 <Hydrate
392 {...belowFoldProps}
393 prefetch={async ({ preload }) => {
394 await preload()
395 }}
396 >
397 <Widget />
398 </Hydrate>
399 )
400}
401```
402β
403Inline `when` and `prefetch` functions are supported. You do not need to wrap
404them in `useCallback`; TanStack Start keeps the latest callback internally and
405does not re-register hydration listeners just because a function identity
406changed. If the meaning of a boundary changes, use a normal React `key` to
407create a new boundary.
408β
409## Hydrate Props Reference
410β
411`Hydrate` accepts these props:
412β
413| Prop | Type | Notes |
414| ------------ | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
415| `when` | `HydrationStrategy \| () => HydrationStrategy` | Required. Controls when the boundary hydrates. Function form is client-only and synchronous. |
416| `prefetch` | `HydrationPrefetchStrategy \| HydrationPrefetchFunction` | Optional. Strategy form preloads the split child chunk. Function form can preload chunks, data, or other resources, and can be used with `split={false}`. |
417| `split` | `boolean` | Defaults to `true`. Set literal `false` to disable compiler extraction and only defer hydration work. |
418| `fallback` | `ReactNode` | Client-only loading UI for boundaries that mount after the app has already hydrated and then suspend on the child chunk or child `Suspense`. |
419| `onHydrated` | `() => void` | Fires once after the boundary has hydrated on the client. |
420β
421## Strategy Reference
422β
423Import strategies from `@tanstack/react-start/hydration`.
424β
425| Strategy | Behavior |
426| --------------- | ------------------------------------------------------------------------------------------ |
427| `load()` | Hydrates as soon as the app hydrates. |
428| `idle()` | Hydrates in `requestIdleCallback`, or after `timeout` when idle callbacks are unavailable. |
429| `visible()` | Hydrates when the boundary marker enters the viewport. |
430| `media()` | Hydrates when the media query matches. |
431| `interaction()` | Hydrates on configured interaction intent events. |
432| `condition()` | Hydrates once the condition is truthy. |
433| `never()` | Never hydrates the initial server-rendered boundary. |
434β
435Strategy options:
436β
437| Strategy | Options |
438| ------------- | --------------------------------------------------------------------------------------- |
439| `idle` | `{ timeout?: number }`, defaults to `2000`. |
440| `visible` | `{ rootMargin?: string; threshold?: number \| Array<number> }`, default margin `600px`. |
441| `media` | Query string, for example `media('(min-width: 800px)')`. |
442| `interaction` | `{ events?: supported event or readonly array of supported events }`. |
443| `condition` | Boolean or boolean-returning function. |
444β
445Supported interaction events are `auxclick`, `click`, `contextmenu`,
446`dblclick`, `focusin`, `keydown`, `keyup`, `mousedown`, `mouseenter`,
447`mouseover`, `mouseup`, `pointerdown`, `pointerenter`, `pointerover`, and
448`pointerup`.
449β
450The default `interaction()` event list is `pointerenter`, `focusin`,
451`pointerdown`, and `click`. Use `events` when a boundary should listen to a
452different event or a smaller set:
453β
454```tsx
455import { Hydrate } from '@tanstack/react-start'
456import { interaction } from '@tanstack/react-start/hydration'
457β
458<Hydrate when={interaction({ events: 'dblclick' })}>
459 <PreviewEditor />
460</Hydrate>
461β
462<Hydrate when={interaction({ events: ['contextmenu', 'dblclick'] })}>
463 <ContextMenuEditor />
464</Hydrate>
465```
466β
467After a `condition()` boundary hydrates, it stays hydrated even if the condition
468later becomes false:
469β
470```tsx
471import { Hydrate } from '@tanstack/react-start'
472import { condition } from '@tanstack/react-start/hydration'
473β
474export function CartRecommendationsBoundary() {
475 return (
476 <Hydrate when={condition(isCartOpen)}>
477 <CartRecommendations />
478 </Hydrate>
479 )
480}
481```
482β
483## Prefetch Reference
484β
485Procedural prefetch receives a context object:
486β
487| Property | Meaning |
488| ------------------- | --------------------------------------------------------------------------------------- |
489| `preload()` | Loads the compiler-generated child chunk. It resolves immediately when `split={false}`. |
490| `waitFor(strategy)` | Waits for a prefetch strategy, the hydration trigger, or abort. |
491| `signal` | `AbortSignal` for cancelable async work such as `fetch`. |
492| `element` | Boundary marker element for custom observers or DOM measurements. |
493β
494`waitFor(strategy)` resolves with:
495β
496| Result | Meaning |
497| ------------ | ------------------------------------------------------------------- |
498| `'prefetch'` | The supplied prefetch strategy resolved normally. |
499| `'hydrate'` | The boundary's hydration trigger fired first. Do required work now. |
500| `'abort'` | The boundary unmounted or the prefetch lifecycle was abandoned. |
501β
502The promise returned from procedural prefetch is meaningful. Awaited work blocks
503hydration if the `when` strategy resolves before the prefetch function
504finishes:
505β
506```tsx
507<Hydrate
508 when={visible()}
509 prefetch={async ({ preload }) => {
510 await preload()
511 }}
512>
513 <Widget />
514</Hydrate>
515```
516β
517Fire-and-forget work does not block hydration:
518β
519```tsx
520<Hydrate
521 when={visible()}
522 prefetch={({ preload }) => {
523 void preload()
524 }}
525>
526 <Widget />
527</Hydrate>
528```
529β
530Use this distinction deliberately. Await when the resource is required for the
531first hydrated render. Fire and forget when the resource is only a helpful
532head start.
533β
534## Fallbacks
535β
536`fallback` is not the placeholder for the initial server-rendered HTML. On the
537initial page load, TanStack Start keeps the existing server HTML in place until
538the boundary hydrates:
539β
540```tsx
541<Hydrate when={visible()} fallback={<ReviewsSkeleton />}>
542 <Reviews />
543</Hydrate>
544```
545β
546In that example, if `Reviews` was present in the initial HTML document, users
547see the server-rendered reviews. They do not see `ReviewsSkeleton` while the
548boundary is waiting for `visible()`.
549β
550`fallback` is used when the boundary first appears after the app is already
551running and there is no existing server HTML for that boundary. Common examples
552include client-side navigation, conditionally showing a panel, or opening a tab
553whose contents were not in the initial document. In those cases, the boundary
554renders on the client, and `fallback` can show while the generated child chunk
555or a child `Suspense` is still loading.
556β
557With `never()`, initial server HTML remains static and `fallback` is not used.
558β
559The compiler removes statically visible `fallback` props from the server bundle.
560Prefer passing `fallback` directly, in an inline object spread, or through a
561single-use `const` object spread so server builds can strip that UI.
562β
563## Correctness And Updates
564β
565Deferred hydration is a performance hint for React's initial hydration work.
566React may hydrate a deferred boundary earlier than its strategy would normally
567allow if state, props, context, or store updates outside the boundary require
568React to reconcile inside it before the gate opens. This preserves correctness
569and avoids showing stale server HTML after the surrounding app has changed.
570β
571`never()` is the exception for initial document hydration. Treat it as
572intentionally static SSR HTML. Do not rely on parent updates to make a `never()`
573boundary interactive. If the same boundary mounts later during client-side
574navigation, it renders normally.
575β
576## Nested Boundaries
577β
578Nested boundaries hydrate parent-first. A child boundary can only hydrate after
579its ancestor boundaries have hydrated. That means non-interaction child
580strategies such as `visible`, `media`, `idle`, or `condition` cannot run while
581their parent boundary is still dehydrated.
582β
583For example, a product page might defer the whole reviews section until it is
584near the viewport, while keeping heavier review tools cold until the user
585interacts with them:
586β
587```tsx
588import { Hydrate } from '@tanstack/react-start'
589import { interaction, visible } from '@tanstack/react-start/hydration'
590β
591export function ProductPage() {
592 return (
593 <>
594 <ProductHero />
595 <BuyBox />
596β
597 <Hydrate when={visible({ rootMargin: '600px' })}>
598 <section aria-labelledby="reviews-heading">
599 <h2 id="reviews-heading">Reviews</h2>
600 <ReviewsSummary />
601 <ReviewsList />
602β
603 <Hydrate when={interaction({ events: ['focusin', 'click'] })}>
604 <ReviewFilters />
605 </Hydrate>
606β
607 <Hydrate when={interaction({ events: 'click' })}>
608 <WriteReviewForm />
609 </Hydrate>
610 </section>
611 </Hydrate>
612 </>
613 )
614}
615```
616β
617In this example, scrolling near the reviews hydrates the parent first. Only
618after that can the nested interaction boundaries hydrate from focus or click.
619β
620Interaction intent can also resolve an unresolved ancestor chain when the
621ancestor is itself waiting for interaction:
622β
623```tsx
624<Hydrate when={interaction({ events: ['focusin', 'click'] })}>
625 <section aria-label="Review tools">
626 <ReviewSortSummary />
627β
628 <Hydrate when={interaction({ events: 'click' })}>
629 <WriteReviewForm />
630 </Hydrate>
631 </section>
632</Hydrate>
633```
634β
635If the first meaningful intent is a click inside `WriteReviewForm`, TanStack
636Start hydrates the unresolved parent chain and then redispatches a same-type
637event for the target boundary. Native listener payload details such as pointer
638coordinates are not guaranteed to be preserved. A `never()` ancestor still wins
639during initial hydration, so descendants under it remain non-interactive.
640β
641## Preloading And CSS
642β
643Transformed `Hydrate` JavaScript chunks are not modulepreloaded with the route.
644Without `prefetch`, the child chunk loads when the split boundary is ready to
645render. If that import suspends during client-side navigation or another
646client-only mount, the boundary's `fallback` is shown.
647β
648CSS used by split, deferred, and `never()` boundaries is linked in the SSR HTML
649for the matched route. It is not deferred with the generated child JavaScript
650chunk, because the server-rendered HTML may need those styles before any
651JavaScript runs. This is route-level asset linking: if a route module contains a
652deferred boundary that imports CSS, that stylesheet can be linked for the route
653even when that boundary is hidden behind conditional rendering and does not
654appear in a particular response.
655β
656## Extraction Limits
657β
658Compiler-backed `Hydrate` splitting works by moving the boundary's children into
659a generated virtual module and rendering them through a lazy component. That
660gives TanStack Start a separate child chunk to load later, but it also means the
661compiler must be able to move the JSX safely.
662β
663Keep the component you want to split directly inside `Hydrate`. If you hide it
664behind opaque `children` props, the compiler cannot statically extract those
665children into a generated child chunk at the usage site.
666β
667The split boundary must use a statically imported `Hydrate` component from
668`@tanstack/react-start`. Renaming that import is supported:
669β
670```tsx
671import { Hydrate as Deferred } from '@tanstack/react-start'
672β
673export function ProductPage() {
674 return (
675 <Deferred when={visible()}>
676 <Reviews />
677 </Deferred>
678 )
679}
680```
681β
682Assigning `Hydrate` to another component variable is not analyzed for splitting:
683β
684```tsx
685import { Hydrate } from '@tanstack/react-start'
686β
687const Deferred = Hydrate
688β
689<Deferred when={visible()}>
690 <Reviews />
691</Deferred>
692```
693β
694Render the imported `Hydrate` tag directly, use an import rename, or set
695`split={false}` when you need component indirection.
696β
697Use the literal prop `split={false}` to opt out of extraction. Dynamic values
698such as `split={shouldSplit}` cannot be used to opt out at compile time.
699β
700These patterns cannot be split:
701β
702| Pattern | Why it is rejected | What to do instead |
703| ---------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
704| Function-as-children | The compiler cannot move a render function and preserve the expected call pattern. | Use `split={false}` or move the rendered UI into a child component. |
705| Hook calls directly inside extracted JSX | Moving that JSX would move where the hook executes. | Move the hook call into a component inside the boundary, then render that component. |
706| `this` captures | Extracted function components cannot safely preserve class instance context. | Wrap the UI in a function component or use `split={false}`. |
707| `super` captures | Extracted function components cannot preserve superclass access. | Wrap the UI in a function component or use `split={false}`. |
708β
709This fails because `useThing()` would be moved into the generated component:
710β
711```tsx
712<Hydrate when={idle()}>
713 <p>{useThing()}</p>
714</Hydrate>
715```
716β
717Move the hook into a component instead:
718β
719```tsx
720function ThingText() {
721 const thing = useThing()
722 return <p>{thing}</p>
723}
724β
725export function ProductPage() {
726 return (
727 <Hydrate when={idle()}>
728 <ThingText />
729 </Hydrate>
730 )
731}
732```
733β
734Values captured from the surrounding component can be passed into the generated
735child component, but keep the boundary simple. If extraction starts forcing
736complicated data flow, prefer a named child component and put the logic there.
737β
738`fallback` stripping is intentionally conservative. The server build can strip
739directly passed fallback UI, inline object-spread fallback UI, and single-use
740`const` object-spread fallback UI. If fallback props are hidden behind dynamic
741spreads or shared objects, the compiler may keep them.
742β
743You can extract reusable `when` and `prefetch` helpers today, but avoid hiding
744split boundaries behind plain wrapper components if you need child code
745splitting. A wrapper can defer hydration at runtime, but the compiler cannot
746reliably move call-site children into a separate chunk through arbitrary
747component indirection.