Server Islands w Astro — dynamiczne fragmenty na statycznej stronie

Odruchowa odpowiedź na potrzebę dynamiki brzmi: „cała strona musi przejść na SSR”. To błąd kosztujący wydajność i budżet CDN. Server Islands zachowują statyczny charakter większości strony, generując na żądanie tylko te fragmenty, które tego faktycznie wymagają.

Czym tak właściwie są Server Islands?

Najprościej rzecz ujmując, Server Island to komponent renderowany po stronie serwera, ale w sposób całkowicie niezależny od głównej strony. Jak to wygląda w praktyce? Pierwsza odpowiedź serwera dostarcza nam statyczny HTML, w którym znajduje się jedynie tzw. placeholder (czyli tymczasowe miejsce zastępcze) tam, gdzie docelowo ma pojawić się nasza dynamiczna treść. Chwilę później, w tle, maleńki skrypt wstrzyknięty przez Astro wysyła kolejne żądanie, pobiera gotową wyspę i płynnie podmienia wstawiony wcześniej placeholder.

Najważniejsza różnica między Server Islands a dobrze znanymi dyrektywami client:* jest fundamentalna: wyspa serwerowa nie renderuje się w przeglądarce użytkownika. Cały proces zachodzi na serwerze i dzięki temu wyspa może bezpośrednio łączyć się z bazą danych, korzystać z bezpiecznych kluczy API (sekretów), czytać ciasteczka i zarządzać sesjami — czyli może wszystko co klasyczny SSR. Przewaga polega na tym, że renderowanie wyspy nie opóźnia wysłania głównego szkieletu strony.

Kiedy Server Islands pokazują pazur?

Oto kilka życiowych przykładów, w których to rozwiązanie sprawdza się idealnie:

Scenariusz 1: Sklep internetowy (karta produktu) Znakomita większość informacji — takich jak opis, zdjęcia, specyfikacja techniczna czy opinie klientów — rzadko ulega zmianie, więc z powodzeniem może być statyczna. Z kolei stan magazynowy to element, który musi być zawsze aktualny. Zanim wprowadzono Server Islands, staliśmy przed trudnym wyborem: albo przerzucamy całą stronę na powolniejszy i droższy SSR, albo ryzykujemy pokazanie klientowi towaru, którego już nie ma w magazynie.

Scenariusz 2: Blog z panelem użytkownika Treść artykułu jest w 100% statyczna i bezpiecznie leży w cache'u. Jednak avatar i spersonalizowane menu nawigacyjne zalogowanego czytelnika w nagłówku strony zależą od sesji i muszą być generowane dynamicznie.

Scenariusz 3: Spersonalizowane rekomendacje na blogu Sam tekst wpisu jest taki sam dla wszystkich, ale sekcja „Polecane dla Ciebie” pod artykułem ma już unikalny charakter i dobiera treści na podstawie profilu lub historii przeglądania danego czytelnika.

We wszystkich tych sytuacjach Server Islands dają nam to, co najlepsze z obu światów: główna treść może być mocno cache'owana (np. z nagłówkiem Cache-Control: public, max-age=3600), a to, co wymaga aktualizacji na żywo, "dociera" do użytkownika chwilę później w formie osobnego zapytania.

Podstawowa konfiguracja

Zanim zaczniemy, coś bardzo ważnego - Server Islands do działania potrzebują adaptera SSR, a w Astro 6 możemy sięgnąć po dowolne wspierane rozwiązanie, na przykład Node, Vercel, Netlify czy Cloudflare:

npx astro add cloudflare
# lub
npx astro add node

Kolejny krok to po prostu dodanie do wybranego komponentu dyrektywy server:defer:

---
// src/pages/blog/[slug].astro
import BlogPost from '../../components/BlogPost.astro';
import UserAvatar from '../../components/UserAvatar.astro';
import RelatedPosts from '../../components/RelatedPosts.astro';
---
 
<main>
  <header>
    <nav>
      <!-- Statyczne linki -->
      <a href="/">Home</a>
      <a href="/blog/">Blog</a>
 
      <!-- Server Island - personalizowany avatar -->
      <UserAvatar server:defer>
        <div slot="fallback" class="avatar-placeholder">
          <!-- Generyczny awatar pokazywany do momentu załadowania się docelowej wyspy -->
        </div>
      </UserAvatar>
    </nav>
  </header>
 
  <!-- Główna treść statyczna -->
  <BlogPost />
 
  <!-- Server Island - rekomendacje -->
  <RelatedPosts server:defer>
    <div slot="fallback">Ładowanie rekomendacji...</div>
  </RelatedPosts>
</main>

Zobaczmy, jak może wyglądać sam komponent takiej wyspy:

---
// src/components/UserAvatar.astro
const sessionCookie = Astro.cookies.get('session');
const userId = sessionCookie ? await validateSession(sessionCookie.value) : null;
 
if (!userId) {
  // Użytkownik jest niezalogowany
  return Astro.redirect('/login');
}
 
const user = await getUserById(userId);
---
 
<div class="user-avatar">
  <img src={user.avatar} alt={user.name} />
  <span>{user.name}</span>
  <a href="/logout/">Wyloguj</a>
</div>

Jak widać, wewnątrz komponentu Server Island możemy swobodnie korzystać z dobrodziejstw środowiska SSR — mamy dostęp do Astro.cookies, Astro.request, możemy odpytywać bazy danych i wczytywać ukryte zmienne środowiskowe. Jednocześnie główna zawartość strony pozostaje nietknięta i wciąż może być błyskawicznie serwowana prosto z cache'a.

Fallback, czyli zadbajmy o odczucia użytkownika

Atrybut slot="fallback" to zdecydowanie coś więcej niż tylko estetyczny dodatek, ponieważ to kluczowy element, który ma realny wpływ zarówno na UX (doświadczenia użytkownika), jak i na wskaźniki Core Web Vitals. Jeśli go z jakiegoś powodu pominiemy, użytkownik najpierw zobaczy pustą dziurę na stronie, a ułamek sekundy później docelowa treść nagle "wskoczy" na swoje miejsce. Taki efekt powoduje nieprzyjemne przesunięcia układu strony (znane jako CLS — Cumulative Layout Shift), a możesz mi wierzyć - algorytmy Google'a bardzo tego nie lubią i może to mieć jakiś wpływ na pozycje strony, nie mówiąc już o negatywnych skutkach dla użytkownika.

Dobra praktyka podpowiada proste rozwiązanie: nasz element zastępczy powinien mieć dokładnie takie same wymiary jak ostateczna zawartość wyspy:

<UserAvatar server:defer>
  <div slot="fallback" style="width: 40px; height: 40px; border-radius: 50%; background: #e5e7eb;">
    <!-- Okrągłe miejsce zastępcze dopasowane rozmiarem do faktycznego awatara -->
  </div>
</UserAvatar>

Podobnie sprawa wygląda w przypadku tzw. skeletonów (ekranów szkieletowych):

<RelatedPosts server:defer>
  <div slot="fallback" class="related-skeleton">
    <div class="skeleton-card" />
    <div class="skeleton-card" />
    <div class="skeleton-card" />
  </div>
</RelatedPosts>

A tak mógłby wyglądać przykładowy kod CSS dla takiego skeletonu (z użyciem frameworka Tailwind CSS):

.skeleton-card {
  @apply h-48 animate-pulse rounded-lg bg-gray-200;
}

Dzięki takiemu podejściu użytkownik od razu dostaje jasny sygnał, że dane wciąż się ładują, a układ strony pozostaje stabilny i nasze wskaźniki CLS utrzymują się na idealnym poziomie.

Jak to wygląda pod maską?

Cały proces renderowania strony z użyciem Server Islands w Astro przebiega w trzech prostych krokach:

1. Każdy komponent oznaczony jako server:defer zostaje wyizolowany i przypisany do specjalnej, ukrytej ścieżki (np. /_server-islands/{nazwa}).
2. W wygenerowanym dokumencie HTML w miejscu komponentu ląduje wspomniany wcześniej placeholder oraz miniaturowy skrypt. Kiedy strona ładuje się w przeglądarce, skrypt ten natychmiast wysyła zapytanie (fetch()) pod adres wygenerowanej wyspy.
3. Serwer zwraca gotowy kod HTML wyspy, który gładko zastępuje tymczasowy placeholder.

Z perspektywy przeglądarki przypomina to następujący scenariusz:

1. GET /blog/moj-wpis               → Pobieramy HTML + fallback + skrypt
2. GET /_server-islands/UserAvatar  → Doczytujemy HTML wyspy
3. JavaScript płynnie podmienia fallback na właściwą treść

Warto zaznaczyć, że wszystkie propsy (właściwości), które przekazujemy do wyspy, są automatycznie szyfrowane unikalnym kluczem (generowanym przy każdym budowaniu projektu) i doczepiane do adresu URL jako parametry. Co nam to daje?

• Możemy bezpiecznie przesyłać poufne dane (jak choćby wewnętrzne identyfikatory) bez obaw, że ktoś złośliwy ręcznie podmieni wartości w adresie.
• Astro domyślnie respektuje nagłówki Cache-Control, więc jeśli wyspa jest wywoływana z dokładnie takimi samymi propsami, systemy takie jak Cloudflare mogą bez problemu zaserwować gotową odpowiedź prosto z pamięci podręcznej.

Należy jednak pamiętać o jednym istotnym ograniczeniu, by długość adresu URL nie przekraczała 2048 bajtów, ponieważ gdy zechcemy przekazać za dużo danych w propsach, Astro automatycznie zmieni typ zapytania na POST i to drastycznie utrudni późniejsze cache'owanie. Praktyczny wniosek jest taki, by przekazywać do wyspy wyłącznie najpotrzebniejsze identyfikatory, a całą resztę obszernych danych dociągać już wewnątrz samego komponentu.

Server Islands vs. Partial Prerendering w Next.js

Brzmi znajomo? Jeśli śledzisz nowości w świecie Next.js (szczególnie od wersji 15), z pewnością kojarzysz technologię Partial Prerendering (PPR) połączoną z mechanizmem strumieniowania (streaming) opartym na komponencie Suspense. Na papierze obie technologie rozwiązują bardzo zbliżony problem, jednak pod spodem działają całkowicie inaczej:

PPR jest głęboko wrośnięty w ekosystem Reacta i zdecydowanie lepiej odnajduje się w cięższych aplikacjach webowych. Z kolei Server Islands to rozwiązanie prostsze koncepcyjnie, które znakomicie wpisuje się w naturę stron zorientowanych na szybkie dostarczanie treści (portale czy blogi). Trudno tu wyłonić jednoznacznego zwycięzcę i lepiej go zresztą nie wyłaniać, ponieważ to po prostu dwa świetne, lecz odmienne narzędzia do osiągnięcia podobnego celu. Chcesz wiedzieć więcej? Zajrzyj do mojego artykułu porównującego fundamenty Astro i Next.js.

Tworzymy licznik komentarzy (przykład praktyczny)

Wyobraźmy sobie taki dość typowy scenariusz: prowadzimy bloga liczącego ponad setkę wpisów, a każdy z artykułów jest generowany statycznie i przez pełną godzinę siedzi bezpiecznie w cache'u CDN. Chcemy jednak, by licznik komentarzy pod wpisem zawsze pokazywał aktualny jego stan.

Gdybyśmy nie użyli Server Islands, prawdopodobnie użylibyśmy zwykłego fetch(), który odpytywałby API z poziomu głównego szablonu. Tyle, że cała strona przymusowo przechodzi na SSR i finalnie bardzo trudno jest ją optymalnie buforować (bo w końcu komentarze ciągle się pojawiają), a sam czas wczytywania ulega wydłużeniu.

Z pomocą Server Islands rozwiązujemy ten problem niezwykle elegancko:

---
// src/pages/blog/[slug].astro
import BlogPost from '../../components/BlogPost.astro';
import CommentsCount from '../../components/CommentsCount.astro';
 
const { post } = Astro.props;
---
 
<BlogPost post={post}>
  <aside class="post-meta">
    <span>
      Komentarze:
      <CommentsCount server:defer postId={post.id}>
        <span slot="fallback" class="inline-block w-8 h-4 bg-gray-200 rounded animate-pulse" />
      </CommentsCount>
    </span>
  </aside>
</BlogPost>

---
// src/components/CommentsCount.astro
const { postId } = Astro.props;
const response = await fetch(`${import.meta.env.API_URL}/comments/count?postId=${postId}`);
const { count } = await response.json();
---
 
<strong>{count}</strong>

Co dzięki temu zyskujemy? Główny artykuł wciąż bezpiecznie "siedzi" w cache'u CDN przez całą godzinę, podczas gdy licznik komentarzy albo odświeża się z każdym odwiedzeniem strony, albo korzysta z osobnego - własnoręcznie ustawionego - buforowania dla danej wyspy.

O czym warto pamiętać? (Ograniczenia i pułapki)

Każda technologia ma swoje własne zasady o których warto wiedzieć od razu:

1. Propsy muszą być bezwzględnie serializowalne. Do wnętrza Server Island nie wrzucisz funkcji, instancji klas ani złożonych komponentów. Musisz cały czas działać na podstawowych formatach danych, czyli typach prostych, tablicach, obiektach JSON czy datach.

2. Uważaj na obiekt Astro.url. Jeśli go wywołasz wewnątrz komponentu wyspy, nie pokaże Ci adresu bazowego (np. /blog/moj-wpis), ale wewnętrzną ścieżkę prowadzącą do wyspy (np. /_server-islands/CommentsCount?...). Potrzebujesz adresu głównej strony? Pobierz go z nagłówka Referer:

---
const referer = Astro.request.headers.get('referer');
const pageUrl = referer ? new URL(referer) : null;
---

3. Wyspy żyją we własnym świecie. Renderują się w całkowitym oderwaniu od reszty drzewa i jeśli na poziomie głównego dokumentu ustawisz jakąś zmienną kontekstową, Twoja wyspa nie będzie miała do niej dostępu. Pamiętaj, że komunikacja musi przebiegać wprost przez zadeklarowane propsy.

4. Uważaj na buforowanie prywatnych danych. Jeśli implementujesz wyspę, która pobiera informacje ściśle przypisane do konkretnego użytkownika (np. wspomniany avatar po zalogowaniu), bezwzględnie zadbaj o dodanie nagłówków Cache-Control: private lub no-store. Brak tej konfiguracji może poskutkować tym, że serwer CDN przypadkowo wyświetli poufne dane innej osobie odwiedzającej Twój serwis.

Dobre praktyki: buforowanie, prywatność i placeholdery

Z Server Islands wyciśniesz maksimum możliwości, pod warunkiem że nauczysz się sprawnie zarządzać trzema odrębnymi warstwami: głównym szkieletem HTML, dynamicznym punktem końcowym samej wyspy oraz jej stanem zastępczym.

Oto złote zasady, których powinieneś się ZAWSZE trzymać:

• Ponieważ główna treść zazwyczaj nie zawiera prywatnych informacji, śmiało nakładaj na nią bardzo rygorystyczne zasady publicznego cache'owania.
• Dla wysp mających poufne dane (tylko do wglądu dla danego użytkownika) zawsze stosuj profil zapobiegawczy — Cache-Control: private albo no-store.
• Kiedy operujesz na danych ogólnodostępnych, ale podlegających częstym rotacjom (jak np. stany magazynowe w sklepie), ustaw dla wyspy bardzo krótki czas trwania pamięci podręcznej (np. s-maxage=60).
• Oszczędzaj bajty, czyli w praktyce - przekazuj wyspie jedynie bazowe identyfikatory i niezbędne minimum informacji, zamiast wrzucać do propsów całe, masywne obiekty pobrane uprzednio z bazy.
• Nie zapominaj także o precyzyjnych wymiarach dla swoich placeholderów, aby uniknąć niepotrzebnego "skakania" elementów na stronie (ma to negatywny wpływ na metryki CLS).

Wydajność — czy to się w ogóle opłaca?

Zazwyczaj tak, aczkolwiek bywają wyjątki od reguły. Server Islands rozwijają skrzydła i pokazują pełen potencjał w różnych sytuacjach:

• Miażdząca większość zawartości strony jest w pełni statyczna, co pozwala na jej drastyczne optymalizowanie za pomocą cache'a.
• Dodawany fragment dynamiczny jest na tyle niewielki, że wygenerowanie drugiego, docelowego żądania odbywa się praktycznie w oka mgnieniu.
• Twoja domena obsługuje zauważalny ruch, przez co korzyści płynące z cache'owania na poziomie CDN stają się łatwo mierzalne.

Trzeba jednak wiedzieć, że to rozwiązanie mija się z celem, gdy:

• Cały Twój projekt ze swej natury (np. zamknięty dashboard dla klientów) opiera się wyłącznie na procesach Server-Side Rendering (SSR).
• Dynamiczna zawartość to w rzeczywistości ogromny moloch (np. paginowana, długa na 50 pozycji sekcja z wynikami wyszukiwania), a w takich przypadkach wymóg wykonania asynchronicznego żądania będzie w praktyce wąskim gardłem i spowolni wczytywanie aplikacji.
• Prowadzisz malutką stronę o bardzo niskim natężeniu ruchu, gdzie stosowanie skomplikowanych wdrożeń z zakresu optymalizacji CDN przynosi mikroskopijne zyski.