← Back to garden

Astro Island Architecture Notes

Evergreen Software Read in Chinese
Created June 10, 2025 Updated January 15, 2026
astro architecture web-dev

What Is Island Architecture

Astro’s Island Architecture splits pages into a static HTML ocean and interactive JavaScript islands. By default, a page is pure HTML/CSS. Only components marked as islands load JavaScript.

The performance impact is immediate: the initial page load skips the entire JavaScript bundle. Users see content fast. Interactivity is injected only where needed.

Hydration Strategy Selection

Astro provides several hydration directives, each suited to different scenarios:

DirectiveBehaviorUsage in This Project
client:loadHydrate immediately on page loadHero 3D scene, language switcher
client:visibleHydrate when entering viewportKnowledge graph, model viewer
client:idleHydrate when browser is idlePagefind search
client:mediaHydrate on media query matchNot used

Selection criteria: if the component is above the fold and needs immediate interaction, use client:load. If below the fold, client:visible. If auxiliary functionality (search), client:idle.

Key Decisions for This Project

One WebGL Context Per Page

Creating a WebGLRenderer and its WebGL context is costly. Browsers typically limit concurrent active contexts (Chrome caps around 16). This project strictly maintains one WebGL context per page.

This means the Hero 3D scene and the knowledge graph never coexist on the same page. If needed in the future, the solution is switching scenes, not creating additional renderers.

GSAP Outside Islands

GSAP scroll animations use Astro’s native <script> tags rather than being wrapped in island components. The reason: GSAP + ScrollTrigger needs control over the entire page scroll state. Wrapping it in an island adds unnecessary complexity.

Under View Transitions, I initialize Lenis + ScrollTrigger on astro:page-load and destroy them on astro:before-swap. This ensures a clean scroll state after every page transition.

Three-Tier Mobile Detection

Using WEBGL_debug_renderer_info for GPU identification, combined with navigator.deviceMemory and prefers-reduced-motion, devices are classified into three tiers:

  • High: Full 3D + post-processing
  • Medium: Simplified 3D, fewer particles, no post-processing
  • Low: 2D fallback (d3-force 2D + CSS animations)

This ensures the Three.js Resource Tracker workload never exceeds device capabilities.

Comparison with Other Frameworks

Before deciding, I also evaluated Next.js and Nuxt. But this project is fundamentally content-driven with no need for server-side state management. Astro’s native content collections with MDX support, combined with static output performance, made it the clear choice.

Open Questions

  • Whether Astro 5’s Server Islands have applicable use cases for this project
  • Progress on View Transitions API support in mobile browsers

Linked from