Astro Islands Hydration Error Fix

In this tutorial, you'll learn about Astro Islands Hydration Error Fix. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

The Problem

An interactive component in Astro does not hydrate. The component renders as static HTML with no interactivity, or the browser console shows hydration errors like Hydration failed because the initial UI does not match what was rendered on the server.

Quick Fix

Step 1: Add a client directive

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

<!-- Wrong — no client directive, component is static -->
<Counter />

<!-- Right — hydrate immediately on page load -->
<Counter client:load />

<!-- Right — hydrate when component is visible -->
<Counter client:visible />

<!-- Right — hydrate when element becomes idle -->
<Counter client:idle />

Expected output: The component hydrates and becomes interactive.

Step 2: Use client:only for browser-only components

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

<!-- Wrong — client:load tries SSR which fails -->
<Chart client:load />

<!-- Right — skip SSR entirely, only render in browser -->
<Chart client:only="react" />

Expected output: Components that access window or document work correctly.

Step 3: Check framework renderer configuration

// astro.config.mjs
import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import preact from '@astrojs/preact';

export default defineConfig({
    integrations: [
        react({ include: ['**/react/*'] }),
        preact({ include: ['**/preact/*'] }),
    ],
});

Expected output: Each framework integration correctly identifies its components.

Step 4: Fix hydration mismatch errors

Hydration mismatches occur when server and client HTML differ:

// Wrong — uses browser API during SSR
function Clock() {
    return <div>{new Date().toLocaleTimeString()}</div>;
}

// Right — only render on client
function Clock() {
    const [time, setTime] = React.useState('');
    React.useEffect(() => {
        setTime(new Date().toLocaleTimeString());
    }, []);
    return <div suppressHydrationWarning>{time}</div>;
}

Expected output: Server and client HTML match, preventing hydration errors.

Step 5: Ensure unique component IDs

// Wrong — duplicate IDs cause hydration issues
function Accordion({ items }) {
    return items.map(item => (
        <div id="accordion">{item}</div>
    ));
}

// Right — unique keys for list items
function Accordion({ items }) {
    return items.map((item, i) => (
        <div key={i}>{item}</div>
    ));
}

Expected output: Each hydrated component has a unique identity.

Step 6: Check for unsupported HTML in framework components

Astro passes HTML through to framework components. Use Astro slots for complex HTML:

<Card client:load>
    <p slot="content">This HTML stays static</p>
</Card>

Expected output: Static HTML is not processed by the framework runtime.

Step 7: Limit client:load usage

Only hydrate components that need interactivity. Overusing client:load increases bundle size:

<!-- Recommended patterns -->
<Header client:load />       <!-- immediate interactivity -->
<ImageGallery client:visible /> <!-- hydrate when scrolled to -->
<Analytics client:media="(min-width: 768px)" /> <!-- responsive hydration -->

Expected output: Only necessary JavaScript is sent to the client.

Prevention

• Always add a client:* directive to interactive components
• Use client:visible for below-the-fold components
• Use client:only for components that access browser APIs
• Add suppressHydrationWarning for dynamic content

Common Mistakes with islands hydration

1. Using return to exit a function early instead of wrapping a pure value in the monad
2. Mixing let bindings with <- bindings in do notation, producing type errors
3. Overlapping type class instances that cause GHC to reject the program with ambiguous dispatch errors

These mistakes appear frequently in real-world ASTRO code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ