dev-create-island

name	dev-create-island
description	Use when adding an interactive UI component that requires client-side JavaScript - creates a framework island with hydration strategy.
user-invocable	true
argument-hint	[IslandName]
allowed-tools	Read, Write, Edit, Bash, Glob, Grep

Create an interactive island component following docs/ARCHITECTURE.md section 5.2.

Island: $ARGUMENTS

Steps

1. Read docs/ARCHITECTURE.md section 5.2.

2. Confirm interactivity is required - if the component is purely presentational, use /dev-create-component instead.

3. Determine the framework (based on project preference):

   • React -> src/islands/IslandName.tsx
   • Vue -> src/islands/IslandName.vue
   • Svelte -> src/islands/IslandName.svelte

4. Choose hydration strategy:

   • client:load - immediately visible + interactive (above the fold)
   • client:idle - not urgent, hydrate when browser is idle
   • client:visible - below the fold, hydrate when scrolled into view
   • client:media="(max-width: 768px)" - only on specific viewports
   • client:only="react" - skip SSR entirely (browser-API-dependent)

5. Create the island with typed props (React example):

interface Props {
  // all props must be serializable (no functions, no class instances)
}

export default function IslandName({ prop1, prop2 }: Props) {
  // minimal client-side state and interactivity
  return (
    <div>
      {/* interactive UI */}
    </div>
  )
}

6. Usage example in .astro file:

---
import IslandName from '../islands/IslandName'
---
<IslandName client:idle prop1="value" prop2={42} />

7. Checklist:

   • Props are serializable (no functions, no class instances)
   • Least aggressive hydration strategy chosen
   • Island scope is minimal (non-interactive parts in .astro)
   • PascalCase filename matching framework convention

8. Validate: npx astro check && npx astro build