AgentSkillsCN

astro-islands

专家 Astro Islands 架构——客户端：加载、空闲、可见、媒体、仅限、服务器：延迟（Server Islands）、备用槽位、过渡：持久、属性序列化。适用于为 Astro 页面添加互动或渲染动态服务器内容时使用。

SKILL.md
--- frontmatter
name: astro-islands
description: Expert Astro Islands Architecture — client:load, client:idle, client:visible, client:media, client:only, server:defer (Server Islands), fallback slots, transition:persist, prop serialization. Use when adding interactivity to Astro pages or rendering dynamic server content.
versions:
  astro: 6
user-invocable: true
references: 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.md
related-skills: astro-6, astro-integrations, astro-actions

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:

  1. •fuse-ai-pilot:explore-codebase - Analyze existing components and hydration patterns
  2. •fuse-ai-pilot:research-expert - Verify latest Islands docs via Context7/Exa
  3. •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

ConceptBenefit
Zero JS by defaultMaximum performance, minimal payload
Selective hydrationOnly interactive components ship JS
server:deferDynamic server content without SSR blocking
client:visibleLazy-load below-fold components
transition:persistState survives page navigation

Client Directives

DirectiveWhen JS LoadsUse Case
client:loadImmediately on page loadCritical interactive UI
client:idleAfter requestIdleCallbackNon-critical UI
client:visibleWhen component enters viewportBelow-fold components
client:media="(query)"When media query matchesResponsive components
client:only="framework"Client-only, no SSRComponents 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

NeedReference
Architecture overviewoverview.md
Client directive detailsclient-directives.md
server:defer patternsserver-islands.md
transition:persisttransitions.md
View Transitions (complete)view-transitions.md
Prop serialization rulesprop-serialization.md
Interactive componenttemplates/interactive-island.md
Server island with fallbacktemplates/server-island.md

Best Practices

  1. •Default to no directive — Ship zero JS unless interactivity is required
  2. •Prefer client:visible — Defer below-fold components automatically
  3. •client:only for browser APIs — localStorage, window, canvas
  4. •server:defer for personalized content — Avatars, prices, auth state
  5. •transition:persist — Preserve media players or forms during navigation