Partial Hydration and Islands Architecture

The Full Hydration Problem

Traditional SSR frameworks (Next.js Pages Router, Remix, Nuxt) hydrate the entire page. Every component — even static headings, paragraphs, and images — downloads JavaScript, re-executes on the client, and hooks into React's runtime.

For a typical content page:

• 90% of components are static (text, images, layout)
• 10% are interactive (buttons, forms, dropdowns)
• 100% of components ship JavaScript and hydrate

That's insane. You're downloading and executing JavaScript for hundreds of components just to make a few buttons clickable.

Islands Architecture

The islands concept, popularized by Jason Miller (of Preact fame) and implemented by Astro, flips the default:

• Static HTML is the default. The page is rendered on the server as pure HTML with zero JavaScript.
• Interactive "islands" opt in to JavaScript. Only the components that need interactivity get hydrated.
• Each island is independent. They hydrate separately, with their own framework instance if needed.

┌──────────────────────────────────────────┐
│  Static HTML (no JS)                      │
│  ┌──────────────────────────────────────┐│
│  │ Navigation                            ││
│  └──────────────────────────────────────┘│
│                                          │
│  ┌───────────┐   Static text...          │
│  │  Search   │   More static text...     │
│  │  Island   │   No JavaScript here.     │
│  │  (React)  │                           │
│  └───────────┘                           │
│                                          │
│  Static content continues...             │
│                                          │
│  ┌──────────────────────────────────────┐│
│  │  Comments Island (Svelte)             ││
│  │  Like button, reply form, etc.        ││
│  └──────────────────────────────────────┘│
│                                          │
│  Static footer (no JS)                   │
└──────────────────────────────────────────┘

Notice: each island can use a different framework. The Search island is React. The Comments island is Svelte. The rest of the page is zero-JS HTML. This is possible because islands are independent — no shared runtime.

How Astro Implements Islands

Astro is the poster child for islands architecture. Every component is static by default. You explicitly opt into client-side JavaScript with a client:* directive.

---
import Header from './Header.astro'
import SearchBar from './SearchBar.tsx'
import BlogContent from './BlogContent.astro'
import CommentsSection from './CommentsSection.tsx'
import Footer from './Footer.astro'
---

<Header />

<SearchBar client:load />

<BlogContent />

<CommentsSection client:visible />

<Footer />

The client:* directives control when the island hydrates:

• client:load — Hydrate immediately when the page loads. For above-the-fold interactive elements.
• client:idle — Hydrate when the browser is idle (requestIdleCallback). For lower-priority interactivity.
• client:visible — Hydrate when the element scrolls into view (Intersection Observer). For below-the-fold content.
• client:media — Hydrate when a CSS media query matches. For responsive interactivity (e.g., mobile menu).
• client:only — Skip SSR entirely, render only on the client. For components that can't server-render.

Partial Hydration vs Islands

These terms are related but distinct:

Partial hydration is the concept — hydrating only parts of the page instead of everything. It's a strategy.

Islands architecture is one implementation of partial hydration — independent, isolated interactive regions in a sea of static HTML.

React's selective hydration (via Suspense boundaries) is a different implementation — it hydrates the whole page, but does it progressively by priority, allowing user interactions to bump hydration order.

The Tradeoff: Isolation

Islands are independent. That independence is both their superpower and their limitation.

The superpower: Each island loads, hydrates, and renders independently. A broken island doesn't crash the page. A slow island doesn't block fast ones. You can even mix frameworks.

The limitation: Islands can't easily share state. In a React SPA, components share state through context, prop drilling, or state managers. In islands architecture, each island has its own React instance — there's no shared context tree.

// This doesn't work across islands:
// Island A: ThemeProvider sets theme
// Island B: useTheme reads it
// They're separate React trees — context doesn't connect them

Solutions for cross-island communication:

• Custom events: document.dispatchEvent(new CustomEvent('theme-change', { detail: 'dark' }))
• Shared store: A vanilla JS store (like nanostores) that islands subscribe to independently
• URL state: Use URL search params for shared state (works across any framework)
• DOM attributes: Write to a data-* attribute that other islands observe

React Server Components vs Islands

RSC and islands solve the same problem (ship less JS) through different mechanisms:

RSC approach: One unified React tree. Server Components are resolved on the server and their output is embedded in the RSC payload. Client Components hydrate within the same React tree. State sharing works normally.

Islands approach: Multiple independent trees. Each island is its own mini-app. No shared React context. Static HTML is the connective tissue.

RSC mental model:
  One big React tree
  ├── Server Component (no JS)
  ├── Server Component (no JS)
  ├── Client Component (ships JS, hydrates)
  ├── Server Component (no JS)
  └── Client Component (ships JS, hydrates)

Islands mental model:
  Static HTML page
  ├── Static HTML
  ├── [Island: React mini-app] (ships JS, hydrates)
  ├── Static HTML
  ├── [Island: Svelte mini-app] (ships JS, hydrates)
  └── Static HTML

RSC keeps the single-tree model React developers know. Islands break it into independent pieces. RSC is better for interactive apps; islands are better for content-heavy sites.