Partial Hydration

Purpose

Partial Hydration addresses the challenge of improving initial page load performance and user experience by delaying the hydration of certain React components. Instead of hydrating the entire React tree immediately on the client, this approach suspends hydration for selected parts until specific data or conditions are ready. This technique reduces the initial JavaScript work, avoids unnecessary rendering, and allows progressive enhancement of the UI.

This subtopic focuses on demonstrating how to implement delayed hydration using React's Suspense mechanism combined with SWR data fetching and debug history tracking, enabling developers to visualize and verify the hydration process step-by-step.

Functionality

The core functionality revolves around suspending component rendering until a predefined asynchronous condition completes, typically a delay or data readiness, then hydrating the component with fresh data fetched via SWR.

Key workflows include:

Suspense Boundary Triggering: The component throws a Promise that resolves after a 2-second delay (susp), causing React to suspend hydration until this Promise resolves.
Data Fetching Post-Suspense: Once the delay resolves, the SWR hook useData fetches data from an API endpoint. The data fetching is decoupled from the initial hydration delay and managed by SWR's cache and revalidation logic.
Debug History Tracking: The hook useDebugHistory is used to attach a debug reference to the DOM, tracking changes in data over time. This helps visualize the hydration process and data updates in the delayed component.

A simplified snippet illustrating the suspense trigger:

if (!resolved) {
  throw susp // suspend hydration until 'susp' Promise resolves
}
const { data } = useData() // fetch data after suspense resolves

The useData hook internally uses SWR to fetch /api/data and extract the desired field:

export default function useData() {
  return useSWR<string>('/api/data', async (url: string) => {
    const res = await fetch(url).then(v => v.json())
    return res.name
  })
}

Integration

Partial Hydration is a specialized technique that complements the broader Server-Side Rendering and Streaming topic by providing fine-grained control over when and how components hydrate on the client.

With SSR & Streaming: It extends SSR by allowing selective hydration delays, reducing client-side blocking and improving perceived performance.
With Suspense & SWR Core: Leverages React Suspense to manage asynchronous rendering boundaries, and SWR for consistent, cached data fetching post-hydration.
With Debugging Tools: Integrates debug history hooks to track state changes during hydration, aiding developers in diagnosing hydration timing and data flow issues.
Distinctive Behavior: Unlike full hydration that happens immediately, Partial Hydration uses suspense to delay rendering of components until their data or conditions are ready, reducing initial load costs without sacrificing interactivity or data freshness.

This approach can be combined with other subtopics such as error handling and retry logic to build resilient, performant React applications with controlled hydration flows.

Diagram

sequenceDiagram
  participant Client as React Client
  participant Suspense as Suspense Boundary
  participant Promise as Delay Promise (susp)
  participant SWR as useSWR Hook
  participant API as /api/data Endpoint

  Client->>Suspense: Render Page component
  Suspense->>Promise: Check if resolved
  Promise-->>Suspense: Not resolved, throw Promise
  Suspense-->>Client: Suspend hydration (show fallback)

  Note over Promise: 2-second delay

  Promise-->>Suspense: Promise resolves
  Suspense->>SWR: Trigger useData SWR fetch
  SWR->>API: Fetch /api/data
  API-->>SWR: Return JSON data
  SWR-->>Suspense: Provide data to component
  Suspense-->>Client: Hydrate component with data

  Client->>DebugHistory: Attach debugRef to track data changes

This sequence diagram illustrates the delayed hydration flow beginning with a suspense-triggering Promise, followed by SWR data fetching, and finishing with hydrated component rendering and debug tracking.