@ilha/astro

An Astro integration that renders and hydrates Ilha islands as Astro components.

Installation

bun add @ilha/astro

Usage

// astro.config.mjs
import { defineConfig } from "astro/config";
import ilha from "@ilha/astro";

export default defineConfig({
  integrations: [ilha()],
});

Then use any Ilha island as an Astro component, with a client directive to control hydration:

---
import { Counter } from "../islands/counter";
---

<Counter client:load start={10} />

How it works

• Server-side: the component is rendered with .hydratable(), which wraps the island's SSR output in a [data-ilha] element carrying serialized props and a state snapshot.
• Client-side: on hydration, the renderer finds that [data-ilha] element inside Astro's island wrapper and calls the island's own .mount() — no re-render, no flicker, .onMount() is skipped since the snapshot already matches the DOM.

Because hydration is driven entirely by Ilha's own data-ilha-* attributes, every Astro client directive (client:load, client:idle, client:visible, client:media, client:only) works as expected.

Notes

• Ilha islands don't support Astro's <slot /> / children forwarding — render everything through the island's own .render() function and props.
• client:only skips SSR entirely and mounts fresh in the browser, matching Astro's usual behavior for other framework renderers.