Przejdź do treści

Jak kontrolować JS w Astro? Dyrektywy klienta w praktyce

Maciej Sala

Founder StriveLab

10 min czytaniaAktualizacja

Szybka odpowiedź: którą dyrektywę client w Astro wybrać?

  • client:visible to domyślny wybór dla komponentów niżej na stronie.
  • client:idle zostaw dla elementów ważnych, ale niepilnych, a client:load dla interakcji krytycznych na pierwszym ekranie.
  • client:media stosuj dla komponentów potrzebnych tylko przy określonej szerokości ekranu.
  • client:only wyłącza renderowanie na serwerze, więc używaj go, gdy komponent lub biblioteka nie obsługuje SSR.
  • Wszystko na client:load niweczy przewagę Astro, dlatego ustal budżet kodu klienta dla typów wysp.

W tym artykule omawiam pięć dyrektyw klienta: kiedy po nie sięgać, kiedy ich unikać i jakie błędy najczęściej wracają w audytach stron na Astro.

Po co są dyrektywy hydratacji client:* w Astro?

Astro domyślnie renderuje komponenty UI do HTML bez wysyłania ich runtime’u do przeglądarki. Własne skrypty i hydratowane wyspy nadal mogą dodawać JavaScript. Jeśli element z Reacta, Vue albo Svelte ma być interaktywny, musisz jawnie określić, kiedy pobrać jego kod i przeprowadzić . Brak automatycznego ładowania całego runtime'u to fundament architektury wysp i jej największa zaleta.

Jeżeli nie wiesz, czym są wyspy w Astro, zacznij od wpisu o Islands Architecture.

Dyrektywa to kontrakt wydajnościowy: wskazujesz frameworkowi, kiedy statyczny HTML ma dostać logikę po stronie klienta. Dzięki temu Astro może wyrenderować bazową treść bez hydratacji, a JavaScript wysłać tylko tam, gdzie jest naprawdę potrzebny.

Jest przy tym jedno ważne ograniczenie: propsy przekazywane do wyspy muszą być serializowalne. Astro zapisuje je w HTML przy użyciu serializatora obsługującego więcej typów niż JSON, m.in. Date, Map, Set, BigInt i wybrane tablice typowane. Funkcje, własne instancje klas czy referencje do komponentów nie są obsługiwanymi propsami hydratacji — takie zależności przenieś do środka wyspy albo zastąp obsługiwanymi danymi.

client:load: natychmiastowa hydratacja komponentu

Code
---
import Navbar from '../components/Navbar.tsx';
---
 
<Navbar client:load />

client:load pobiera i uruchamia kod JavaScript komponentu jak najszybciej, kiedy tylko przeglądarka przetworzy HTML. Jest to najbardziej agresywna dyrektywa i powinna być zarezerwowana dla elementów, które muszą działać od razu.

Kiedy używać client:load:

  • Nawigacja główna z rozwijanym menu, które prawdopodobnie użytkownik otworzy jako pierwsze.

  • Przycisk CTA w głównej sekcji (hero), który musi otworzyć okno modalne.

  • Przełącznik motywu (ciemny/jasny), który ma szybko reagować na kliknięcie. Początkowy motyw ustal osobno przed pierwszym wyświetleniem treści, np. CSS-em, na serwerze lub krótkim skryptem — client:load nie zapobiega sam w sobie migotaniu.

Kiedy NIE używać client:load:

  • Formularze kontaktowe w stopce, ponieważ do nich użytkownik musi przewinąć stronę i dlatego client:visible w zupełności wystarczy.

  • Komentarze pod wpisem (z analogicznego powodu jak wyżej).

  • Galeria zdjęć, którą widać dopiero po kliknięciu w miniaturkę.

Kluczem do sukcesu jest selektywność. Nieuzasadniony client:load może zwiększyć transfer i pracę głównego wątku, pogarszając m.in. . Znaczenie ma koszt pobrania i wykonania kodu, a nie sama liczba wysp.

client:idle: hydratacja, gdy przeglądarka jest bezczynna

Code
---
import NewsletterSignup from '../components/NewsletterSignup.tsx';
---
 
<NewsletterSignup client:idle />

client:idle czeka na wywołanie — moment, w którym przeglądarka zakończyła krytyczne zadania i procesor ma wolny cykl. Jeśli przeglądarka nie obsługuje requestIdleCallback, Astro używa zdarzenia load; w nowszych wersjach możesz też ustawić limit oczekiwania przez client:idle={{ timeout: 500 }}.

Kiedy używać:

  • Komponenty ważne, ale nie krytyczne dla pierwszej interakcji — zapis na newsletter, widżet czatu, baner zgody na pliki cookie. Przy zgodach marketingowych tryb ładowania komponentu musi być spójny z tym, kiedy uruchamiasz skrypty śledzące.

  • Widżety dostawców zewnętrznych opakowane w komponent frameworka, które wpływają na interaktywność, ale nie stanowią priorytetu.

  • Przyciski udostępniania w mediach społecznościowych.

Kiedy NIE używać:

  • Elementy znajdujące się poza początkowo widocznym obszarem strony, których załadowanie można odłożyć, używając client:visible.

  • Krytyczne elementy interfejsu (okna modalne, główna nawigacja).

W praktyce client:idle często przesuwa hydratację poza krytyczny start strony — i właśnie takie odroczenie potrafi obniżyć koszt JavaScriptu widoczny w TBT oraz w diagnostyce Lighthouse.

client:visible: hydratacja po wejściu komponentu w viewport

Code
---
import CommentsSection from '../components/CommentsSection.tsx';
import ProductGallery from '../components/ProductGallery.tsx';
---
 
<article>
  <!-- długa treść artykułu -->
</article>
 
<CommentsSection client:visible />

client:visible wykorzystuje , aby pobrać i uruchomić JavaScript dopiero wtedy, gdy dana sekcja pojawi się w widocznym obszarze ekranu. Jeśli warunek widoczności nie zostanie spełniony, ta wyspa nie rozpocznie ładowania; wspólne zależności mogą jednak zostać wcześniej pobrane przez inne wyspy.

client:visible to domyślna rekomendacja dla elementów poniżej linii przewijania. Daje realną oszczędność, bo kod ładuje się dopiero wtedy, gdy jest szansa na interakcję.

Kiedy używać client:visible:

  • Sekcja komentarzy pod artykułem.
  • Formularz kontaktowy w stopce lub na samym dole strony.
  • Galeria zdjęć znajdująca się poniżej opisu produktu.
  • Kalkulator lub interaktywny widżet osadzony w środku wpisu.

  • Karuzela z logotypami klientów.

Kiedy NIE używać client:visible:

  • Elementy pierwszego ekranu, bo są widoczne od razu. W takim miejscu client:visible nie optymalizuje ładowania, tylko dokłada narzut obserwatora (IntersectionObserver).

  • Wyspy współdzielące stan z innymi częściami interfejsu, bo opóźniona hydratacja może spowolnić synchronizację danych.

Możesz też skonfigurować parametr client:visible, aby rozpocząć pobieranie kodu JS i hydratację zanim komponent fizycznie wejdzie w widoczny obszar:

Code
<CommentsSection client:visible={{ rootMargin: "200px" }} />

Dzięki temu kod ładuje się, gdy komponent znajduje się np. 200 pikseli poniżej aktualnego widoku. Daje to więcej czasu na hydratację, ale nie gwarantuje gotowości przed interakcją — zależy ona także od sieci, urządzenia i rozmiaru kodu. Pobieranie może rozpocząć się, nawet jeśli użytkownik zatrzyma przewijanie przed samą sekcją.

client:media: hydratacja po spełnieniu media query

Code
---
import MobileNav from '../components/MobileNav.tsx';
import DesktopSidebar from '../components/DesktopSidebar.tsx';
---
 
<div class="mobile-nav">
  <MobileNav client:media="(width < 1024px)" />
</div>
<div class="desktop-sidebar">
  <DesktopSidebar client:media="(width >= 1024px)" />
</div>
 
<style>
  .desktop-sidebar { display: none; }
  @media (min-width: 1024px) {
    .mobile-nav { display: none; }
    .desktop-sidebar { display: block; }
  }
</style>

client:media uruchamia hydratację dopiero po spełnieniu wskazanego media query, ale nie ukrywa HTML wyrenderowanego na serwerze. W przykładzie widocznością steruje CSS, a warunki hydratacji pokrywają cały zakres szerokości. Przykładowo, na smartfonie DesktopSidebar nie pobierze swojego kodu JS, a MobileNav zostanie pominięty na komputerze stacjonarnym. Warunek jest nasłuchiwany na żywo: po obrocie tabletu albo zwężeniu okna hydratacja ruszy w momencie dopasowania, ale już zhydratowany komponent pozostaje interaktywny nawet po późniejszej zmianie rozmiaru.

Kiedy używać client:media:

  • Elementy interfejsu przeznaczone wyłącznie na urządzenia mobilne, czyli menu typu hamburger, wysuwane panele dolne (bottom sheets), galerie obsługujące gesty przesunięcia (swipe).

  • Elementy wyłącznie desktopowe, takie jak rozbudowane menu rozwijane po najechaniu kursorem, skomplikowane filtry wykorzystujące mechanizm przeciągnij i upuść.

  • Responsywne widżety, które mają kompletnie inną logikę działania w zależności od rozmiaru ekranu.

Kiedy NIE używać client:media:

  • Kiedy komponent dostosowuje się tylko wizualnie (za pomocą CSS media queries), ale nie zmienia logiki biznesowej.

  • Gdy zachowanie różni się zaledwie szczegółem, wtedy prościej jest użyć client:visible i wewnątrz komponentu weryfikować warunki przez window.matchMedia.

Po tę dyrektywę sięgam rzadko, ale w specyficznych sytuacjach, np. przy ciężkim wysuwanym panelu mobilnym, który na desktopie nie istnieje, pozwala zaoszczędzić dziesiątki kilobajtów transferu. Innymi słowy, wdrażamy ją tylko wtedy, gdy logika po obu stronach ekranu jest wyraźnie inna.

client:only: komponent wyłącznie po stronie klienta

Code
---
import ChartWidget from '../components/ChartWidget.tsx';
import ClientSideMap from '../components/InteractiveMap.tsx';
---
 
<ChartWidget client:only="react" />
<ClientSideMap client:only="react" />

client:only to sygnał dla Astro, żeby nie renderować komponentu po stronie serwera () i wygenerować go wyłącznie w przeglądarce. Działa to odwrotnie do pozostałych dyrektyw.

Kiedy używać client:only:

  • Komponenty zależne w fazie renderowania od obiektów globalnych przeglądarki takich jak window, document czy localStorage, ponieważ bez tego proces SSR zakończyłby się błędem.

  • Biblioteki, które nie posiadają wsparcia dla SSR (np. niektóre nakładki na Three.js, react-leaflet, edytory tekstu typu WYSIWYG).

  • Komponenty, których zależności od API przeglądarki nie da się odroczyć do etapu po zamontowaniu bez rezygnacji z SSR.

  • Elementy, których wygląd jest bardzo mocno uzależniony od dokładnego rozmiaru okna, a wersja wyrenderowana na serwerze i tak wymagałaby natychmiastowego przebudowania przez JS.

Samo użycie window, localStorage czy IndexedDB nie wymaga client:only. Często można zachować HTML z serwera, a odczyt danych przenieść do efektu lub obsługi zdarzenia. Początkowy render klienta powinien wtedy zgadzać się z renderem serwera.

Kiedy NIE używać client:only:

  • We wszystkich innych przypadkach. Użycie client:only dezaktywuje mechanizm SSR, przez co rezygnujesz z błyskawicznego serwowania gotowej treści. Zamiast tego zmuszasz użytkownika do oczekiwania, aż pobierze się JS i wygeneruje komponent bezpośrednio w jego przeglądarce.

Sprawdzoną praktyką przy korzystaniu z client:only jest dodanie zastępczego szkieletu (placeholdera):

Code
<div class="min-h-[400px] flex items-center justify-center">
  <ClientSideMap client:only="react">
    <p slot="fallback">Ładowanie mapy...</p>
  </ClientSideMap>
</div>

Przykład zakłada Tailwind CSS lub zdefiniowanie odpowiadających tym klasom stylów. Rezerwacja miejsca ogranicza przesunięcia układu (), ale min-height: 400px nie gwarantuje ich braku, jeśli mapa okaże się wyższa. Dopasuj wysokość lub proporcje kontenera do końcowego komponentu.

Porównanie dyrektyw client:* w Astro

DyrektywaKiedy ładuje JSKiedy używaćKiedy unikać
client:loadNatychmiastKrytyczne interakcje na pierwszym ekranie (nawigacja, główne przyciski)Elementy widoczne dopiero po przewinięciu
client:idleGdy przeglądarka jest bezczynnaWażne, ale nie priorytetowe elementy (newsletter, czat)Krytyczny interfejs, komponenty reagujące na przewijanie
client:visibleGdy element wchodzi w pole widzeniaWszystko poniżej pierwszego ekranuElementy widoczne od razu po załadowaniu
client:mediaGdy spełnione są reguły media queryInterfejsy specyficzne tylko dla mobile / desktopGdy zmienia się wyłącznie wygląd, a nie logika
client:onlyNatychmiast, ale bez SSR — HTML powstaje dopiero w przeglądarceBiblioteki niekompatybilne z SSR, wymagające okna przeglądarkiKażdy element, który można bez problemu wyrenderować na serwerze

Budżet hydratacji w Astro

W większych projektach warto ustalić limit kodu klienta dla każdego typu wyspy, ponieważ określenie takiego budżetu chroni przed sytuacją, w której strona Astro ma być lekka, a w praktyce wysyła kilka masywnych paczek.

przykładowy cel liczby wysp client:load, nie limit Astro
1–2przykładowy cel liczby wysp client:load, nie limit Astro
JavaScript dla elementów czysto wizualnych bez interakcji
0 KBJavaScript dla elementów czysto wizualnych bez interakcji
  • Pierwszy ekran: 1–2 wyspy z client:load mogą być punktem wyjścia dla prostej strony, ale budżet ustalaj według transferu i czasu wykonania. Kilka małych wysp może kosztować mniej niż jedna duża.
  • Niższe sekcje strony: client:visible jako domyślny wybór.
  • Detale wizualne i dekoracje: brak hydratacji, chyba że wprost wpływają na konwersję.
  • Komponenty wymagające API przeglądarki: najpierw rozważ efekt lub obsługę zdarzenia; client:only zostaw dla kodu niekompatybilnego z SSR.
  • Zależności współdzielone: regularna weryfikacja, czy mała wyspa nie importuje całej biblioteki wykresów, edytora WYSIWYG albo kitu.

Najczęstsze błędy przy dyrektywach client:*

W audytach stron Astro notorycznie spotykam trzy te same kategorie błędów:

1. Nadużywanie client:load. Przykładem jest serwis na Astro, który ma osiem wysp oznaczonych client:load i ładuje cały ich JavaScript już na starcie. Warto sprawdzić koszt tych wysp i zasadność ładowania każdej od razu; sama liczba ośmiu nie dowodzi problemu.

2. Layout owinięty w jeden wielki React z client:load. Programista przyzwyczajony do Next.js może odruchowo budować Layout.tsx z nagłówkiem, treścią i stopką, a potem oznaczyć całość client:load. Layout w .astro i punktowo osadzone wyspy to dobra konwencja, nie wymóg frameworka. Komponent frameworkowy bez dyrektywy klienta może również pozostać statycznym HTML.

3. client:only bez elementu zastępczego. Komponent ładuje się po 1,5 s, strona nieprzyjemnie skacze, a CLS niebezpiecznie rośnie. Zawsze ustaw kontener zastępczy z odpowiednią wysokością na czas ładowania.

Praktyczny przykład: karta produktu e-commerce w Astro

Przeanalizujmy dobór odpowiednich dyrektyw przy projektowaniu standardowej podstrony produktowej:

Code
---
// src/pages/produkt/[slug].astro
import Layout from '../../layouts/Layout.astro';
import Header from '../../components/Header.astro';
import ProductImages from '../../components/ProductImages.tsx';
import AddToCart from '../../components/AddToCart.tsx';
import ProductDescription from '../../components/ProductDescription.astro';
import Reviews from '../../components/Reviews.tsx';
import RecentlyViewed from '../../components/RecentlyViewed.tsx';
import Footer from '../../components/Footer.astro';
 
// Minimalny przykład SSG; w projekcie pobierz produkty z CMS-a lub API.
export function getStaticPaths() {
  const products = [{
    slug: 'przykladowy-produkt',
    id: 'product-1',
    images: ['/images/product-1.jpg'],
    description: 'Opis przykładowego produktu.',
  }];
 
  return products.map((product) => ({
    params: { slug: product.slug },
    props: { product },
  }));
}
 
const { product } = Astro.props;
---
 
<Layout>
  <Header />
 
  <main>
    <!-- Galeria widoczna od razu, istnieje wysokie prawdopodobieństwo wejścia w interakcję -->
    <ProductImages images={product.images} client:load />
 
    <!-- Przycisk dodawania do koszyka (CTA) o kluczowym znaczeniu dla konwersji -->
    <AddToCart productId={product.id} client:load />
 
    <!-- Czysto statyczny tekst opisu, nie generuje JS -->
    <ProductDescription content={product.description} />
 
    <!-- Sekcja opinii umieszczona niżej, aktywuje się dopiero przy przewijaniu -->
    <Reviews productId={product.id} client:visible />
 
    <!-- Karuzela "Ostatnio przeglądane" pobiera kod JS w wolnej chwili -->
    <RecentlyViewed client:idle />
  </main>
 
  <Footer />
</Layout>

Przykład zakłada komponenty obsługujące pokazane propsy i obraz dostępny pod wskazaną ścieżką. Przy renderowaniu na żądanie zamiast getStaticPaths() pobierz produkt według Astro.params.slug.

Taka konfiguracja pokazuje HTML wyrenderowany przez komponenty na serwerze, bez oczekiwania na pobranie skryptów. Krytyczne strefy interfejsu (galeria zdjęć, przycisk zakupu) są szybko hydratowane i gotowe do akcji, a skrypty opinii ładują się dopiero wtedy, gdy użytkownik przewinie stronę do danej sekcji. Odroczenie mniej pilnych elementów może zmniejszyć koszt początkowego ładowania, ale jego efekt trzeba zmierzyć. Treść pobierana dopiero w efektach komponentów nie znajdzie się automatycznie w początkowym HTML.

Audyt hydratacji własnej strony Astro

Jeśli rozwijasz już projekt w Astro, wdróż ten czteropunktowy audyt:

  1. Przeszukaj kod pod kątem client:load — każda taka deklaracja musi być nieodzowna na pierwszym ekranie.
  2. Rozważ client:visible dla elementów poza pierwszym ekranem, uwzględniając zależności, wspólny stan i wymaganą gotowość do interakcji.
  3. Znajdź każde client:only — udokumentuj komentarzem, dlaczego SSR jest tu niemożliwy. Część przypadków da się przepisać.
  4. Uruchom Lighthouse Mobile i porównaj laboratoryjne TBT, CLS i LCP. INP sprawdzaj podczas rzeczywistych interakcji oraz w danych użytkowników — zwykły audyt ładowania Lighthouse go nie mierzy. TBT poniżej 200 ms to punkt odniesienia, nie gwarancja dobrego INP. TTI usunięto z Lighthouse 10.

Jeśli chcesz zlecić profesjonalny audyt techniczny SEO Twojej witryny w Astro — wejdź na wyższy poziom i odezwij się.

Ultraszybkie projekty, łączące lekkość ze skalowalnością.
Astro

Często zadawane pytania

Czym różni się `client:idle` od `client:visible`?

client:idle pobiera JavaScript tuż po załadowaniu strony, gdy tylko przeglądarka ma wolny zasób lub minie zadany timeout – bez względu na pozycję komponentu w układzie. Natomiast client:visible uruchamia ładowanie dopiero w momencie, gdy komponent pojawia się w viewporcie użytkownika; jeśli sekcja nie zostanie przewinięta, kod nie zostanie pobrany (chyba że współdzielone zależności ściągnie inna wyspa). client:visible stanowi więc optymalny wybór dla większości komponentów umieszczonych poniżej linii przewijania.

Czy mogę łączyć dyrektywy na jednym komponencie?

Nie łącz kilku dyrektyw hydratacji na jednej wyspie; komponent może też pozostać bez dyrektywy. Złożony harmonogram wymaga własnej dyrektywy klienta lub osobno zaprojektowanego ładowania. client:media nie łączy warunków idle i visible, a kod wewnątrz wyspy zaczyna działać dopiero po jej uruchomieniu.

Czy `client:only` ma wpływ na SEO?

Tak, i zazwyczaj jest to wpływ negatywny. Dyrektywa client:only całkowicie wyłącza renderowanie po stronie serwera (SSR), przez co zawartość komponentu w ogóle nie trafia do początkowego kodu HTML. Choć współczesne roboty indeksujące radzą sobie z uruchamianiem JavaScriptu, generuje to dodatkowy koszt renderowania i drastycznie zwiększa ryzyko opóźnionej indeksacji. W przypadku kluczowych treści pod kątem SEO stosowanie client:only jest po prostu błędem architektonicznym.

Dlaczego mój komponent z `client:load` ładuje się powoli?

Przyczyną może być zbyt duży rozmiar paczki, wolna sieć, zablokowany główny wątek albo wysoki koszt samego renderowania i hydratacji. Choć client:load oznacza uruchomienie skryptu „tak szybko, jak to możliwe”, przeglądarka i tak musi najpierw pobrać kod z sieci. Jeśli zależności komponentu ważą 200 KB, sama dyrektywa nic nie pomoże – prawdziwa optymalizacja musi uderzyć w kod źródłowy, czyli w dynamiczne importy, tree shaking czy zastąpienie ciężkich bibliotek lżejszymi alternatywami.

Czy muszę używać dyrektyw dla komponentów `.astro`?

Nie. Komponenty .astro renderują się podczas buildu lub na serwerze i nie wymagają hydratacji frameworkowej. Mogą jednak zawierać skrypty przeglądarkowe oraz osadzać hydratowane wyspy. Dyrektywy client:* dotyczą wyłącznie komponentów z frameworków UI: React, Vue, Svelte, Solid, Preact.

O autorze

Maciej Sala

Maciej Sala — konsultant technologiczny produktów cyfrowych i web developer z bogatym doświadczeniem w marketingu internetowym oraz SEO. Na co dzień pracuje z Reactem, Next.js i TypeScriptem, a ostatnio także z Astro i narzędziami do automatyzacji procesów AI. Sprawnie łączy perspektywę produktową z praktycznym podejściem do kodu. Przez kilka lat był związany z branżą gier wideo jako project manager i game designer. Absolwent historii na Uniwersytecie Jagiellońskim oraz studiów podyplomowych z marketingu internetowego na AGH w Krakowie. Po godzinach trenuje na siłowni, maluje figurki i rozwija własne projekty.

Pomagam przekładać takie tematy na konkretne wdrożenia w frontendzie, SEO, analityce i procesie produktowym.

Skontaktuj się ze mną
LH.pl – Hosting Mango

Biblioteka wiedzy na temat Astro

Czytaj dalej

Zobacz więcej wpisów
Architektura wysp i selektywna hydratacja w frameworku Astro

„Zero JavaScript domyślnie” nie jest obietnicą wyniku Lighthouse, lecz regułą kompilacji: komponent Astro i komponent frameworka bez dyrektywy client: nie wysyłają swojego runtime'u do przeglądarki. Skrypty analityczne, widżety, router i jawne nadal mogą zwiększyć budżet JavaScriptu. W artykule pokazuję, jak działają granice wysp, kiedy opóźniać hydratację i jak nie zamienić selektywnej interaktywności w serię „martwych” kliknięć.

Maciej Sala

Maciej Sala

Founder StriveLab

Astro czy Next.js w 2026: porównanie frameworków

Astro czy Next.js? Wybór frameworka musi być dokładnie przemyślany, zanim pojawi się pierwszy commit. Jeśli stoisz przed takim właśnie wyborem, w tym artykule staram się wykazać, w jakich obszarach najlepiej sprawdza się Astro , a w jakich będzie dominował Next.js .

Maciej Sala

Maciej Sala

Founder StriveLab

Framework Astro w praktyce: przewodnik od architektury po utrzymanie

Strona internetowa może mieć świetny wynik PageSpeed, a mimo to wciąż mieć różne problemy, poczynając od blokowania publikacji artykułów, a kończąc na gubieniu zapytania z formularza. Stworzyłem ten przewodnik, by sprawnie prowadził przez wybór technologii, migrację, model treści, rendering, SEO i testy, aż po wdrożenie i utrzymanie. Szczegółowe rozwiązania znajdziesz w materiałach przypisanych do poszczególnych etapów.

Maciej Sala

Maciej Sala

Founder StriveLab

LH.pl – Cloud Server 1C4G