Astro- und React-Islands einrichten

Zum Initialisieren eines Astro-Projekts verwenden Sie npx create astro@latest. Dadurch wird ein interaktiver Assistent gestartet, in dem Sie ein Template, TypeScript-Einstellungen und einen Paketmanager auswählen. Astro unterstützt mehrere Starter, darunter ein leeres Template, ein Blog-Template und Templates für Dokumentationen.

Astro-Integrationen fügen einem Projekt die Unterstützung für Frameworks hinzu. Wenn Sie npx astro add react ausführen, werden @astrojs/react, react und react-dom automatisch installiert. Außerdem wird astro.config.mjs aktualisiert, sodass es die React-Integration enthält. Die gesamte Einrichtung erfolgt mit einem einzigen Befehl.

Eine .astro-Datei ist das Komponentenformat von Astro. Sie besteht aus einem Frontmatter-Bereich (JavaScript zwischen ----Begrenzern) und einem Template-Bereich. Standardmäßig erzeugt eine Astro-Datei statisches HTML – an den Browser wird kein JavaScript gesendet, solange Sie nicht ausdrücklich eine Client-Direktive hinzufügen.

Der Import einer React-Komponente in eine Astro-Datei verwendet die standardmäßige ES-Modul-Syntax: import Counter from './Counter.jsx'. Ohne Client-Direktive rendert Astro die React-Komponente serverseitig als statisches HTML und sendet dieses HTML an den Browser – für die Komponente wird kein JavaScript ausgeliefert.

Wenn Sie dem Komponententag im Astro-Template client:visible hinzufügen, wird daraus ein Island: <Counter client:visible />. Astro liefert nun das JavaScript von Counter aus, hydriert die Komponente, sobald sie in den sichtbaren Bereich gescrollt wird, und macht sie interaktiv. Ohne die Direktive bleibt sie statisches HTML.

React-Komponenten, die als Astro-Islands verwendet werden, werden mit Standard-React geschrieben – sie verwenden Hooks, State, Effekte und beliebige React-Bibliotheken. Innerhalb der React-Komponente selbst gibt es keine Astro-spezifische API. Die Island-Grenze wird im Astro-Template und nicht im Code der Komponente definiert.

Jede Island-Instanz ist ein unabhängiger React-Baum. Zwei Counter-Islands auf derselben Seite teilen sich ihren State nicht. Wenn Sie gemeinsamen State benötigen, haben Sie drei Möglichkeiten: Fassen Sie sie zu einem Island zusammen, verwenden Sie URL-Suchparameter für serialisierbaren State oder nutzen Sie eine Bibliothek für gemeinsamen State wie nanostores.

Die Bibliothek @nanostores/react stellt leichtgewichtige Atome bereit, die jedes Island abonnieren kann. Ein Island schreibt in ein Nano-Store-Atom, ein anderes Island liest daraus. Da Nano-Stores frameworkunabhängig sind, funktioniert dieses Muster auch zwischen React- und Vue-Islands auf derselben Seite.

Astro Content Collections bieten eine typsichere Möglichkeit, Markdown- und MDX-Dateien zu verwalten. Definieren Sie ein Collection-Schema mit Zod, legen Sie Markdown-Dateien in src/content/ ab, und Astro erzeugt vollständig typisierte Abfragefunktionen. Dies ist das Standardmuster für Blogbeiträge, Dokumentationen und Produktseiten.

Durch die Ausführung von astro build wird ein Ordner dist/ mit statischen HTML-Dateien erzeugt. Für jede Seite gibt Astro eine HTML-Datei mit den serverseitig gerenderten Inhalten und nur den JavaScript-Bundles aus, die für die Islands auf dieser Seite benötigt werden. Seiten ohne Islands enthalten kein JavaScript.

Das statische Ergebnis kann ohne Server auf jedem CDN (Netlify, Vercel, Cloudflare Pages) bereitgestellt werden. Für Anforderungen an serverseitiges Rendering (dynamische Routen, API-Endpunkte) unterstützt Astro SSR-Adapter für Node.js, Vercel Edge, Cloudflare Workers und Deno. Islands funktionieren in beiden Modi identisch.

Welche minimale Änderung muss an einer importierten React-Komponente in einem Astro-Template vorgenommen werden, damit sie auf dem Client interaktiv wird?

Richten Sie Astro mit React mithilfe von npx astro add react ein. Astro-Dateien sind standardmäßig statisch. Wenn Sie dem Tag einer React-Komponente eine client:-Direktive hinzufügen, wird daraus ein hydriertes Island. React-Komponenten sind normales React und verwenden keine Astro-spezifischen APIs. Der State ist pro Island isoliert; nanostores ermöglichen die Kommunikation zwischen Islands. Der Build erzeugt statisches HTML mit genau dem benötigten JavaScript für die Islands.