Islands Architecture

Islands Architecture is a web rendering pattern where a page is mostly static server-rendered HTML, with small isolated regions of interactive JavaScript (the islands) that hydrate independently on the client. Each island ships only the code it needs, leaving the rest of the page as plain HTML.

In Plain Words

Picture a magazine page that is mostly text and images, with a few interactive widgets dropped in: a search box, a video player, a comments thread. Islands Architecture treats a webpage the same way. The page itself is HTML, sent and rendered by the server. Only the bits that genuinely need JavaScript become islands, and each one boots up on its own.

The contrast is with the typical single-page app, where the entire page is one giant JavaScript component tree. There, the browser downloads, parses, and rehydrates the whole thing before anything becomes interactive, even the parts that never move.

How It Works

A framework that supports the pattern does three things at build or request time:

• Render the full page to HTML on the server, including the markup that an island would eventually produce.
• Identify which components are interactive and emit only their JavaScript bundles, scoped to the island.
• Insert a small runtime that hydrates each island in place, often lazily, when the island enters the viewport or the user interacts with it.

In Astro, the syntax is a directive on the component:

---
import Counter from '../components/Counter.jsx';
---

<h1>A mostly static page</h1>
<p>Plain HTML, no JS.</p>

<Counter client:visible />

Everything outside the <Counter /> tag ships zero JavaScript. The counter itself ships its component, its framework runtime, and nothing more. The client:visible hint tells the runtime to wait for an IntersectionObserver to fire before hydrating.

Different frameworks pick different defaults. Fresh ships islands by file convention. Marko detects which components have state. Eleventy plus is-land uses a custom element wrapper. The mechanics differ. The shape is the same.

Why It Matters

Hydration is the part of a modern web app where the browser re-executes component code on top of server-rendered HTML to wire up event handlers and state. It is also where most of the JavaScript cost lives. A page that hydrates everything pays for interactivity it does not use.

Islands flip the default. Static is free. Interactivity is opt-in, scoped, and parallel. The practical effects:

• Less JavaScript on the wire, often by an order of magnitude on content-heavy sites.
• Faster time-to-interactive, because each island hydrates on its own rather than waiting for one giant bundle.
• Resilience to slow networks, since the page is already usable as HTML before any JS arrives.
• Easier mixing of frameworks. A React island and a Svelte island can live on the same page.

The trade-off is that cross-island state is awkward. Two islands that need to share data cannot just import a React context. They communicate through the URL, custom events, or a tiny shared store loaded as its own module. For app-shaped UIs with deep shared state (dashboards, editors, design tools), the pattern fits poorly. For content-shaped sites like docs, marketing, blogs, and e-commerce, it fits well.

Origin

The term was coined by Katie Sylor-Miller, then a frontend architect at Etsy, in 2019. Jason Miller (creator of Preact) wrote the post that popularized it: Islands Architecture on jasonformat.com in August 2020.

The pattern itself predates the name. Etsy and other large e-commerce sites had been mounting isolated interactive widgets on otherwise-static pages for years. Naming it gave framework authors something to target, and Astro, Fresh, Marko, and Eleventy all followed.

Common Confusions

Islands Architecture is often mixed up with adjacent ideas. The distinctions matter when picking a framework.