Also covers transition:persist for preserving component state across View Transitions, and prop serialization rules for data crossing the server/client boundary. Does not cover installing the underlying UI framework itself (astro-integrations) or Server Actions used inside islands (astro-actions) — those are separate skills.
Astro Islands Expert
Partial hydration architecture: zero JS by default, selective interactivity via directives.
Agent Workflow (MANDATORY)
Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:
- 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:only for browser APIs — localStorage, window, canvas
server:defer for personalized content — Avatars, prices, auth state
transition:persist — Preserve media players or forms during navigation
1---2name: astro-islands3description: Use when adding interactivity to Astro pages via client:* directives or rendering dynamic server content with server:defer.4versions:5 astro: 76user-invocable: true7references: references/overview.md, references/client-directives.md, references/server-islands.md, references/transitions.md, references/view-transitions.md, references/prop-serialization.md, references/templates/interactive-island.md, references/templates/server-island.md8related-skills: astro-7, astro-integrations, astro-actions9metadata:10 source: https://skillmd.com/skills/fusengine/astro-islands11---1213<objective>14Implements Astro's Islands Architecture: partial hydration via `client:load`, `client:idle`, `client:visible`, `client:media="(query)"`, and `client:only="framework"`, plus Server Islands via `server:defer` (with `slot="fallback"` placeholders) for personalized or auth-gated content rendered after initial page load without blocking SSR.1516Also covers `transition:persist` for preserving component state across View Transitions, and prop serialization rules for data crossing the server/client boundary. Does not cover installing the underlying UI framework itself (astro-integrations) or Server Actions used inside islands (astro-actions) — those are separate skills.17</objective>1819# Astro Islands Expert2021Partial hydration architecture: zero JS by default, selective interactivity via directives.2223## Agent Workflow (MANDATORY)2425Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:26271. **fuse-ai-pilot:explore-codebase** - Analyze existing components and hydration patterns282. **fuse-ai-pilot:research-expert** - Verify latest Islands docs via Context7/Exa293. **mcp__context7__query-docs** - Get client directive and server:defer examples3031After implementation, run **fuse-ai-pilot:sniper** for validation.3233---3435## Overview3637### When to Use3839- Adding interactive React/Vue/Svelte/Solid components to Astro pages40- Deferring dynamic server content without blocking page load41- Persisting component state during View Transitions42- Optimizing Time to Interactive with lazy hydration4344### Why Islands Architecture4546| Concept | Benefit |47|---------|---------|48| Zero JS by default | Maximum performance, minimal payload |49| Selective hydration | Only interactive components ship JS |50| `server:defer` | Dynamic server content without SSR blocking |51| `client:visible` | Lazy-load below-fold components |52| `transition:persist` | State survives page navigation |5354---5556## Client Directives5758| Directive | When JS Loads | Use Case |59|-----------|--------------|----------|60| `client:load` | Immediately on page load | Critical interactive UI |61| `client:idle` | After `requestIdleCallback` | Non-critical UI |62| `client:visible` | When component enters viewport | Below-fold components |63| `client:media="(query)"` | When media query matches | Responsive components |64| `client:only="framework"` | Client-only, no SSR | Components using browser APIs |6566## Server Islands6768`server:defer` renders the component on the server after the page loads:6970- Uses `slot="fallback"` for placeholder content71- Ideal for personalized or auth-gated content72- Does not block initial page render73- Requires a server adapter7475---7677## Reference Guide7879| Need | Reference |80|------|-----------|81| Architecture overview | [overview.md](references/overview.md) |82| Client directive details | [client-directives.md](references/client-directives.md) |83| server:defer patterns | [server-islands.md](references/server-islands.md) |84| transition:persist | [transitions.md](references/transitions.md) |85| View Transitions (complete) | [view-transitions.md](references/view-transitions.md) |86| Prop serialization rules | [prop-serialization.md](references/prop-serialization.md) |87| Interactive component | [templates/interactive-island.md](references/templates/interactive-island.md) |88| Server island with fallback | [templates/server-island.md](references/templates/server-island.md) |8990---9192## Best Practices93941. **Default to no directive** — Ship zero JS unless interactivity is required952. **Prefer `client:visible`** — Defer below-fold components automatically963. **`client:only` for browser APIs** — localStorage, window, canvas974. **`server:defer` for personalized content** — Avatars, prices, auth state985. **`transition:persist`** — Preserve media players or forms during navigation