Islands Architecture

Islands architecture reduces unnecessary client-side JavaScript — only hydrate interactive parts of the page.

01 — Purpose

Hydrate islands, not oceans

Islands architecture reduces unnecessary client-side JavaScript — only hydrate interactive parts of the page.

Most pages are mostly static: headings, prose, images, links. Islands architecture keeps that HTML server-rendered or pre-built, and loads JavaScript only for components that need it — search, cart, tabs, date picker.

This site is built with Astro — an islands model by default. See hydration costs and JS module architecture.

02 — Principles

Interactivity loads intentionally

Reduced JS cost, faster rendering, and improved resilience.

  • isolated interactivity — each island owns its JS boundary
  • progressive enhancement — page works without island scripts
  • restrained hydration — default static; opt in to client behaviour

03 — Practice

Good islands architecture

Ship HTML first; add client runtime only where interaction demands it.

  • identify interactive boundaries — form, nav toggle, filter panel — not whole layout
  • colocate island scripts — small entry points per feature, not one app bundle
  • use framework island directives — e.g. client:load, client:visible when appropriate
  • pair with progressive hydration — defer non-critical islands
  • keep islands accessible without JS — links and forms still submit

04 — Avoid

Island anti-patterns

Islands fail when everything becomes an island or nothing shares conventions.

  • hydrating entire pages unnecessarily — SPA wrapper around static content
  • over-fragmented systems — dozens of micro-islands with duplicated runtime cost
  • islands that require JS for basic navigation or reading
  • shared state spaghetti across islands — unclear data flow
  • ignoring bundle size per island — see JavaScript cost

05 — Close

Static by default

Ask of every component: does this need client JavaScript on first load?

Default to zero JS. Add an island when interaction, client state, or browser APIs require it — and choose the lightest client directive that meets the need.

See progressive hydration, static vs SSR vs CSR, and performance standard.