Astro Islands Expert
Partial hydration architecture: zero JS by default, selective interactivity via directives.
Agent Workflow (MANDATORY)
Before ANY implementation, use TeamCreate to spawn 3 agents:
- fuse-ai-pilot:explore-codebase - Analyze existing components and hydration patterns
- fuse-ai-pilot:research-expert - Verify latest Islands docs via Context7/Exa
- mcp__context7__query-docs - Get client directive and server:defer examples
After implementation, run fuse-ai-pilot:sniper for validation.
Overview
When to Use
- Adding interactive React/Vue/Svelte/Solid components to Astro pages
- Deferring dynamic server content without blocking page load
- Persisting component state during View Transitions
- Optimizing Time to Interactive with lazy hydration
Why Islands Architecture
| Concept | Benefit |
|---|---|
| Zero JS by default | Maximum performance, minimal payload |
| Selective hydration | Only interactive components ship JS |
server:defer | Dynamic server content without SSR blocking |
client:visible | Lazy-load below-fold components |
transition:persist | State survives page navigation |
Client Directives
| Directive | When JS Loads | Use Case |
|---|---|---|
client:load | Immediately on page load | Critical interactive UI |
client:idle | After requestIdleCallback | Non-critical UI |
client:visible | When component enters viewport | Below-fold components |
client:media="(query)" | When media query matches | Responsive components |
client:only="framework" | Client-only, no SSR | Components using browser APIs |
Server Islands
server:defer renders the component on the server after the page loads:
- Uses
slot="fallback"for placeholder content - Ideal for personalized or auth-gated content
- Does not block initial page render
- Requires a server adapter
Reference Guide
| Need | Reference |
|---|---|
| Architecture overview | overview.md |
| Client directive details | client-directives.md |
| server:defer patterns | server-islands.md |
| transition:persist | transitions.md |
| View Transitions (complete) | view-transitions.md |
| Prop serialization rules | prop-serialization.md |
| Interactive component | templates/interactive-island.md |
| Server island with fallback | templates/server-island.md |
Best Practices
- Default to no directive — Ship zero JS unless interactivity is required
- Prefer
client:visible— Defer below-fold components automatically client:onlyfor browser APIs — localStorage, window, canvasserver:deferfor personalized content — Avatars, prices, auth statetransition:persist— Preserve media players or forms during navigation