中文
devexamples
← Recipes

阅读中文版本

Hydrate Islands Progressively

Hydrate interactive components on idle or on visibility so static content is interactive without blocking the main thread.

~30 minfrontendperformancehydration

Task

Use progressive hydration strategies so non-critical interactive components load without blocking.

When to use this

A content-heavy page loads thousands of lines of JavaScript up front even though most components are below the fold.

Prerequisites

  • A framework with island hydration
  • Interactive components
  • A performance measurement setup

Steps

1. Hydrate on visibility or idle instead of immediately.

<Chart client:visible />
<Comments client:idle />
<Search client:load />

Expected output: Only the critical Search hydrates immediately; the rest wait for visibility or idle.

2. Verify main-thread blocking improves.

npx lighthouse http://localhost:4321/ --only-categories=performance --output=json

Expected output: Total blocking time drops because most hydration is deferred.

Troubleshooting

Problem

Interactive element unresponsive until scrolled

Solution

Use client:load for anything the user interacts with immediately.

Problem

Layout shift on hydration

Solution

Reserve space for components so hydration does not move content.

Limitations

  • Deferred hydration delays interactivity.
  • Determining the right strategy needs measurement.
  • Does not reduce total JavaScript shipped.

What this recipe does

Use progressive hydration strategies so non-critical interactive components load without blocking.

A content-heavy page loads thousands of lines of JavaScript up front even though most components are below the fold.

Prerequisites

  • A framework with island hydration
  • Interactive components
  • A performance measurement setup

Procedure

  1. Hydrate on visibility or idle instead of immediately.
<Chart client:visible />
<Comments client:idle />
<Search client:load />

Expected result: Only the critical Search hydrates immediately; the rest wait for visibility or idle.

  1. Verify main-thread blocking improves.
npx lighthouse http://localhost:4321/ --only-categories=performance --output=json

Expected result: Total blocking time drops because most hydration is deferred.

How to confirm it worked

Run the commands above and confirm every expected result in order. If a step does not produce the stated output, use the troubleshooting notes before continuing. A passing run shows total blocking time falls while critical components remain interactive immediately.

Troubleshooting

Interactive element unresponsive until scrolled — Use client:load for anything the user interacts with immediately.

Layout shift on hydration — Reserve space for components so hydration does not move content.

Limitations

  • Deferred hydration delays interactivity.
  • Determining the right strategy needs measurement.
  • Does not reduce total JavaScript shipped.