Konfiguracja Astro i React Islands

Utworzenie projektu Astro odbywa się za pomocą npx create astro@latest, które uruchamia interaktywny kreator pozwalający wybrać szablon, ustawienia TypeScriptu i menedżera pakietów. Astro obsługuje wiele szablonów startowych, w tym pusty szablon, szablon bloga oraz szablony dokumentacji.

Integracje Astro dodają do projektu obsługę frameworków. Uruchomienie npx astro add react automatycznie instaluje @astrojs/react, react i react-dom, a także aktualizuje astro.config.mjs, dodając do niego integrację React. Cała konfiguracja wymaga tylko jednego polecenia.

Plik .astro to format komponentu Astro. Składa się z sekcji front matter (JavaScriptu umieszczonego między znacznikami ---) oraz sekcji szablonu. Domyślnie plik Astro generuje statyczny HTML — do przeglądarki nie jest wysyłany żaden JavaScript, chyba że jawnie dodadzą Państwo dyrektywę klienta.

Importowanie komponentu React do pliku Astro odbywa się za pomocą standardowej składni modułów ES: import Counter from './Counter.jsx'. Bez dyrektywy klienta Astro renderuje komponent React po stronie serwera do postaci statycznego HTML i wysyła ten HTML do przeglądarki — dla komponentu nie jest wysyłany żaden JavaScript.

Dodanie client:visible do znacznika komponentu w szablonie Astro przekształca go w wyspę: <Counter client:visible />. Astro wysyła teraz kod JavaScript komponentu Counter, przeprowadza jego hydratację, gdy komponent pojawi się w obszarze widocznym w oknie, i zapewnia mu interaktywność. Bez tej dyrektywy jest on statycznym HTML-em.

Komponenty React używane jako wyspy Astro są pisane w standardowym React — korzystają z hooków, stanu, efektów i dowolnej biblioteki React. Sam komponent React nie używa żadnego API specyficznego dla Astro. Granica wyspy jest definiowana w szablonie Astro, a nie wewnątrz kodu komponentu.

Każda instancja wyspy jest niezależnym drzewem React. Dwie wyspy Counter na tej samej stronie nie współdzielą stanu. Jeśli potrzebują Państwo współdzielonego stanu, mają Państwo trzy możliwości: połączyć je w jedną wyspę, użyć parametrów zapytania URL do przechowywania stanu możliwego do serializacji albo skorzystać ze współdzielonej biblioteki stanu, takiej jak nanostores.

Biblioteka @nanostores/react udostępnia lekkie atomy, do których może subskrybować się dowolna wyspa. Jedna wyspa zapisuje wartość w atomie nano store, a inna ją odczytuje. Ponieważ nano stores są niezależne od frameworka, ten wzorzec działa również między wyspami React i Vue na tej samej stronie.

Astro Content Collections zapewniają bezpieczny typowo sposób zarządzania plikami Markdown i MDX. Należy zdefiniować schemat kolekcji za pomocą Zod, umieścić pliki Markdown w src/content/, a Astro wygeneruje w pełni typowane funkcje zapytań. To standardowy wzorzec używany w przypadku wpisów blogowych, dokumentacji i stron produktów.

Uruchomienie astro build generuje folder dist/ zawierający statyczne pliki HTML. Dla każdej strony Astro tworzy plik HTML z treścią wyrenderowaną po stronie serwera oraz tylko tymi paczkami JavaScript, które są potrzebne wyspom na danej stronie. Strony bez wysp nie zawierają żadnego JavaScriptu.

Statyczne dane wyjściowe można wdrożyć w dowolnej sieci CDN (Netlify, Vercel, Cloudflare Pages) bez serwera. Jeśli potrzebne jest renderowanie po stronie serwera (dynamiczne trasy, punkty końcowe API), Astro obsługuje adaptery SSR dla Node.js, Vercel Edge, Cloudflare Workers i Deno. Wyspy działają identycznie w obu trybach.

Jaka minimalna zmiana w imporcie komponentu React w szablonie Astro jest potrzebna, aby stał się on interaktywny po stronie klienta?

Należy skonfigurować Astro z React za pomocą npx astro add react. Pliki Astro są domyślnie statyczne; dodanie dyrektywy client: do znacznika komponentu React przekształca go w hydratowaną wyspę. Komponenty React są standardowymi komponentami React i nie korzystają z API specyficznych dla Astro. Stan jest odizolowany w każdej wyspie, a nanostores umożliwia komunikację między wyspami. Kompilacja generuje statyczny HTML oraz tylko ten kod JavaScript wysp, który jest potrzebny.