Islands Architecture — Islands of Interactivity in a Sea of Static HTML

In this tutorial, you will learn about Islands Architecture. We cover key concepts, practical examples, and best practices to help you master this topic.

Islands architecture renders interactive components as isolated islands in static HTML, sending JavaScript only for those islands while the rest remains pure HTML without hydration.

What You'll Learn

By the end of this tutorial, you will understand the islands architecture pattern, how it differs from traditional SSR, how to identify which components should be islands, how frameworks like Astro and Qwik implement islands, and how this pattern leads to near-zero JavaScript by default.

Why It Matters

Islands architecture is the most aggressive approach to reducing JavaScript in SSR applications. By default, no component sends JavaScript to the browser. Only explicitly marked interactive islands hydrate. This results in the smallest possible JavaScript bundles and the fastest Time to Interactive.

Real-World Use

A content site with 100,000+ pages adopted Astro with islands architecture. The average page sent 12KB of JavaScript — 95 percent less than the previous React SPA. Despite the dramatic JS reduction, the site retained full interactivity for search, navigation, and comments. Lighthouse performance scores went from 45 to 98.

Islands Architecture Concept
    ┌──────────────────────────────────────────────────────────┐
    │              Islands Architecture                         │
    ├──────────────────────────────────────────────────────────┤
    │                                                          │
    │  ┌──────────────────────────────────────────────────┐    │
    │  │           Sea of Static HTML                      │    │
    │  │  ┌──────────┐                    ┌──────────┐   │    │
    │  │  │  Island  │                    │  Island  │   │    │
    │  │  │  Search  │                    │   Cart   │   │    │
    │  │  │  (React) │                    │  (Preact)│   │    │
    │  │  └──────────┘                    └──────────┘   │    │
    │  │                                                   │    │
    │  │     ┌──────────────────────────────┐              │    │
    │  │     │         Island               │              │    │
    │  │     │     Newsletter Form           │              │    │
    │  │     │       (Vue.js)               │              │    │
    │  │     └──────────────────────────────┘              │    │
    │  │                                                   │    │
    │  │            Static Content                          │    │
    │  │  · Article text (no JS)                           │    │
    │  │  · Images (lazy loaded)                           │    │
    │  │  · Footer links (static)                          │    │
    │  └──────────────────────────────────────────────────┘    │
    │                                                          │
    │  Each island can use a different framework              │
    │  Islands are independent — no shared state              │
    │  Static content is server-rendered HTML                 │
    │                                                          │
    └──────────────────────────────────────────────────────────┘

Think of islands architecture like an archipelago. The ocean (static HTML) surrounds each island (interactive component). The islands are independent — each has its own ecosystem (JavaScript framework) and does not rely on other islands. You can visit (interact with) any island without needing to visit all of them.

Identifying Islands in a Page

// Page audit — which parts need to be islands?
function auditPageForIslands() {
    const pageElements = [
        { name: 'Header navigation', interactive: false },
        { name: 'Search bar', interactive: true },
        { name: 'Hero section (CSS animation)', interactive: false },
        { name: 'Product cards (static)', interactive: false },
        { name: 'Add to cart button', interactive: true },
        { name: 'Price filter slider', interactive: true },
        { name: 'Customer reviews', interactive: false },
        { name: 'Pagination', interactive: false },
        { name: 'Newsletter form', interactive: true },
        { name: 'Footer links', interactive: false },
        { name: 'Back to top button', interactive: true },
        { name: 'Cookie consent banner', interactive: true },
    ];

    const islands = pageElements.filter(el => el.interactive);
    const static_ = pageElements.filter(el => !el.interactive);

    console.log(`Total components: ${pageElements.length}`);
    console.log(`Islands (need JS): ${islands.length}`);
    console.log(`Static (no JS): ${static_.length}`);
    console.log(`JS reduction: ${Math.round((1 - islands.length / pageElements.length) * 100)}%`);
}

// Expected output:
// Total components: 12
// Islands (need JS): 6
// Static (no JS): 6
// JS reduction: 50%

Implementing Islands with Different Frameworks

---
// Astro — different frameworks for different islands
// Server-side rendering, zero JS by default
---

<!-- PREACT island for the search component -->
<SearchBar
    client:load
    data={searchData}
/>

<!-- REACT island for the product carousel -->
<ProductCarousel
    client:visible
    products={products}
/>

<!-- VUE island for the newsletter form -->
<NewsletterForm client:idle />

<!-- SVELTE island for the live chat -->
<LiveChat client:only="svelte" />

<!-- SolidJS island for the real-time counter -->
<ViewerCount client:load />

<!-- No framework needed for static components -->
<StaticFooter />

Common Mistakes

1. Making static content interactive by default. The default in islands architecture should be no JavaScript. Only add interactivity when there is a clear user need.
2. Islands that depend on each other. Islands should be independent. If two islands need to share state, consider merging them into one island or using a global event bus.
3. Large islands. If an island contains too many components, its JavaScript bundle becomes large. Break large islands into smaller, independent ones.
4. Mixing frameworks without a plan. Islands can use different frameworks, but each framework adds bundle weight. Stick to one or two frameworks for consistency.
5. Not accounting for layout shift. Islands that hydrate later (client:visible, client:idle) should not cause layout shift when they become interactive. Reserve space for them.

Practice Questions

1. What is the core principle of islands architecture?
2. How do you decide which components should be islands?
3. What are the benefits of independent islands?
4. How does Astro implement islands architecture?
5. How do you prevent layout shift from deferred island hydration?

Challenge: Audit a complex page (like a news homepage or e-commerce listing) and identify which components must be islands (interactive) and which can remain static. Build the page using Astro or a manual islands pattern. Achieve under 50KB of JavaScript sent to the client.

FAQ

Mini Project

Build a product page with islands architecture: use Astro (or manual islands) with a React island for the image gallery carousel, a Preact island for the Add to Cart form, a Vue island for the customer reviews widget (with star ratings), and the rest of the page as static HTML (product description, specs, related products, footer).

What's Next

You understand islands architecture. Now explore SSR Caching to optimize server rendering performance.