Szybka odpowiedź: jak przyspieszyć Next.js za pomocą streamingu i Suspense?
- Wolne fragmenty owiń w małe granice
<Suspense>, a Next.js wyśle najpierw powłokę i dośle resztę. loading.tsxtworzy taką granicę dlapage.tsxi potomków, ale nie dlalayout.tsxz tego samego segmentu.- Niezależne zapytania uruchamiaj równolegle, żeby nie tworzyć kaskady.
- Streaming nie przyspiesza samego zapytania, a fallback musi mieć wymiary treści, żeby nie psuć CLS.
- Przy własnym hostingu sprawdź, czy reverse proxy albo CDN nie buforuje odpowiedzi.
Na czym polega streaming w Next.js?
W klasycznym renderowaniu serwerowym bez mechanizmu streamowania aplikacja musi zebrać wszystkie dane potrzebne do zbudowania całej strony, zanim użytkownik cokolwiek zobaczy. Mimo że same zapytania mogą biec równolegle, pojedyncze wolne oczekiwanie umieszczone wysoko w drzewie komponentów skutecznie blokuje wyrenderowanie wszystkiego poniżej.
Streaming całkowicie zmienia ten model, pozwalając wysłać wstępną powłokę strony wraz z fallbackami, zanim zakończą się wolniejsze operacje, a następnie sukcesywnie uzupełniać treść w miarę gotowości poszczególnych granic. Warto jednak pamiętać, że natychmiastowe ładowanie nie jest dane raz na zawsze, ponieważ czas dotarcia pierwszego fragmentu zależy między innymi od zadań wykonywanych przed granicą, generowania metadanych dla botów oraz pośredniego buforowania po drodze.
Next.js App Router obsługuje streaming natywnie, wykorzystując React Suspense i architekturę Server Components.
Jak działa Suspense w Server Components?
<Suspense> to granica, która mówi Reactowi: „wyświetl fallback (np. skeleton), a gdy dane będą gotowe, wtedy podmień na właściwą treść". Zwykły fetch w useEffect lub handlerze zdarzenia nie uruchamia automatycznie tego fallbacku. Poniższy przykład korzysta z asynchronicznego Server Component.
Przykłady pokazują układ granic: komponenty prezentacyjne, takie jak StatCard, WelcomeBanner i pozostałe sekcje oraz ich importy, są skrótami do implementacji projektu. Adresy api.example.com zastąp własnym API.
Kolejność wyświetlania przy Suspense
Niezależne granice Suspense ujawniają się w kolejności, w jakiej spływają ich dane, a nie według ułożenia w drzewie JSX. W sytuacji, kiedy RevenueChart otrzyma dane w 500 ms, a DashboardStats w 2 s, wykres pojawi się jako pierwszy – mimo że w kodzie znajduje się niżej. Każdy blok <Suspense> działa tu jak osobna „wyspa” streamowania.
Nie oznacza to jednak, że struktura JSX nie ma znaczenia. Zagnieżdżona granica nie zostanie pokazana, dopóki nie wyrenderuje się jej granica nadrzędna, a żądanie uruchomione dopiero po zakończeniu pracy innego komponentu wywoła klasyczny waterfall. Granice Suspense decydują więc o tym, kiedy ujawnia się UI, ale to struktura komponentów i miejsce inicjowania zapytań (promise’ów) kontrolują, kiedy te dane w ogóle zaczynają się pobierać.
loading.tsx: Suspense na poziomie routingu
Next.js App Router ma wbudowany mechanizm, który automatycznie owija page.tsx w <Suspense>. Wystarczy dodać plik loading.tsx w tym samym katalogu.
loading.tsx tworzy granicę Suspense dla page.tsx i potomnych segmentów danego poziomu routingu, podczas gdy współdzielony layout pozostaje widoczny i interaktywny. Ręczne <Suspense> pozwala wydzielić konkretne sekcje niezależnie. W praktyce możesz łączyć oba podejścia. Ta granica nie obejmuje jednak layout.tsx z tego samego katalogu: wolne pobieranie w nim wymaga własnego Suspense albo przeniesienia niżej. Bez Cache Components może blokować nawigację, a przy włączonych Cache Components dostęp do danych runtime poza granicą może powodować błąd podczas budowania.
Projektowanie dobrych skeletonów w Next.js
to narzędzie UX, które redukuje postrzegany czas ładowania, a dobrze zaprojektowany skeleton:
Odwzorowuje kształt docelowej treści, czyli użytkownik mentalnie widzi stronę zanim się załaduje.
Unika migotania: dla bardzo szybkich danych rozważ opóźnione pokazanie fallbacku; próg dobierz na podstawie pomiarów, nie sztywnej reguły 200 ms.
Jest lekki i nie zawiera ciężkich animacji, które obciążają GPU.
Fallback powinien być w pełni dostępny dla każdego użytkownika, dlatego dekoracyjne kształty należy ukryć przed czytnikami za pomocą atrybutu aria-hidden, a stan ładowania komunikować na kontenerze sekcji przy użyciu aria-busy="true" lub dedykowanego elementu z role="status". Warto również wyłączyć animacje dla użytkowników preferujących ograniczony ruch, używając zapytania prefers-reduced-motion. Po pomyślnym załadowaniu właściwej treści należy niezwłocznie usunąć atrybut aria-busy, pamiętając, aby nie ogłaszać każdej karty osobno, co mogłoby przytłoczyć odbiorcę korzystającego z technologii asystujących.
Unikanie flash of loading state
Jeśli dane ładują się szybko, skeleton migocze na ułamek sekundy i to jest gorsze niż brak skeletonu. W tej sytuacji CSS może pomóc:
Skeleton dopasowany do rodzaju sekcji
Nie buduj jednego uniwersalnego placeholdera dla całej aplikacji, bo takie rozwiązanie się po prostu nie sprawdzi. Przykładowo, karta produktu potrzebuje miejsca na zdjęcie, cenę i CTA, tabela powinna zachować liczbę kolumn, a artykuł może pokazać jedynie szerokości akapitów. Dzięki temu po doładowaniu danych układ nie przeskakuje, a użytkownik od razu rozumie strukturę widoku.
W ramach prostego testu porównaj wymiary skeletonu z finalnym komponentem i sprawdź CLS w Lighthouse albo danych rzeczywistych. Jeżeli fallback zmienia wysokość sekcji lub spycha najważniejszą treść, ładowanie wizualnie szkodzi nawet wtedy, gdy streaming działa technicznie poprawnie.
Streaming i Suspense a Core Web Vitals
Streaming może wpływać na metryki , których dane rzeczywiste Google wykorzystuje jako jeden z sygnałów jakości strony:
LCP przy streamingu w Next.js
Streaming może poprawić LCP tylko wtedy, gdy kandydat LCP znajduje się w szybko dostarczonej powłoce albo rozwiązuje się wcześniej niż bez streamingu. Jeśli największym elementem jest obraz lub hero ukryte za wolną granicą, LCP nadal będzie późny, a zastąpienie dużego skeletonu właściwą treścią może wyznaczyć nowego kandydata LCP. Mierz wynik w danych rzeczywistych, a nie na podstawie samego użycia Suspense.
INP przy streamingu i Suspense
React łączy streaming z selektywną hydratacją, więc może wcześniej priorytetyzować interaktywne fragmenty. Nie gwarantuje to poprawy INP: ciężki kod klienta, długie zadania na głównym wątku i kosztowne handlery nadal decydują o opóźnieniu interakcji. Server Components bez JavaScriptu klienta nie wymagają hydratacji; hydratowane są interaktywne Client Components.
CLS i stabilność skeletonów
Streaming może pogorszyć CLS, jeśli skeletony mają inne wymiary niż docelowa treść. Rozwiązanie: projektuj skeletony z identyczną wysokością i układem jak finalne komponenty.
Streaming a SEO: co widzi Googlebot?
Streaming w App Routerze nadal jest renderowaniem serwerowym, ale nie warto opierać SEO na założeniu, że każdy robot poczeka na każdą spóźnioną granicę. Treść kluczową dla znaczenia strony trzymaj w statycznej powłoce albo szybko rozwiązującej się granicy. Cięższe sekcje pomocnicze streamuj później.
Najbezpieczniejsze założenie jest takie:
- Tytuł, lead, H1, opis i główna treść powinny być dostępne bez długiego czekania na request-time data.
- Skeleton nie jest treścią SEO i traktuj go wyłącznie jako element UX.
- Jeśli ważna sekcja streamuje się długo albo zależy od personalizacji, nie zakładaj, że każdy crawler zobaczy ją tak samo szybko jak użytkownik.
- Weryfikuj efekt w praktyce przez Google Search Console i renderowany HTML.
W Next.js 16 dynamiczne generateMetadata może być streamowane niezależnie od UI i wstrzykiwane po rozwiązaniu obietnicy. Dla botów wymagających metadanych w <head>, takich jak Twitterbot, Slackbot czy Bingbot, Next.js domyślnie wyłącza ten mechanizm i czeka na metadane przed rozpoczęciem streamingu. Zachowanie można zmienić opcją htmlLimitedBots, ale nie rób tego bez testów crawlerów i podglądów udostępniania.
Weryfikacja: użyj inspekcji adresu URL w Google Search Console, wykonaj test wersji opublikowanej i sprawdź wyrenderowany HTML. Dodatkowo porównaj „Wyświetl źródło strony” z DOM-em w DevTools. Źródło może zawierać całą odebraną odpowiedź, w tym późniejsze fragmenty HTML i skrypty zastępujące fallbacki; DOM pokazuje wynik ich przetworzenia. Samo źródło nie pokazuje kolejności ani czasu dostarczenia fragmentów — do tego użyj obserwacji strumienia i pomiarów opisanych niżej.
Zaawansowane wzorce Suspense w Next.js
Zagnieżdżony Suspense
Możesz zagnieżdżać granice, tworząc hierarchię ujawniania treści:
Grupowanie granic Suspense
Jeśli kilka komponentów powinno pojawić się razem, grupuj je w jednej granicy. Jeżeli mają niezależne czasy oczekiwania i mogą pojawiać się osobno, oddzielne granice dadzą szybsze częściowe ujawnienie.
Streaming z Promise.all dla równoległych fetchów
Poniżej znajdziesz alternatywną implementację DashboardStats, która wciąż renderuje się pod granicą Suspense. Użyty tu typ generyczny definiuje oczekiwaną strukturę odpowiedzi, ale nie weryfikuje JSON-a w trakcie działania programu – dlatego kontrakt z API należy zabezpieczyć dodatkową walidacją zgodną ze schematem danych.
Wywołania fetchJson() rozpoczynają niezależne operacje bez oczekiwania na poprzednią, a Promise.all oczekuje na ich wyniki. Komponent może się ujawnić dopiero po zakończeniu wszystkich operacji; błąd jednej odrzuca wynik Promise.all, lecz nie anuluje pozostałych żądań. Użyj tego wzorca, gdy dane tworzą jedną logiczną sekcję. Jeżeli części mają pojawiać się niezależnie, rozdziel je na osobne komponenty i granice Suspense. Niezależna obsługa awarii wymaga dodatkowo osobnych granic błędów lub jawnej obsługi błędów sekcji — same granice Suspense jej nie zapewniają. Gdy jedno zapytanie wymaga wyniku poprzedniego, sekwencja jest uzasadniona, ponieważ streaming może pokazać wcześniejszy etap, ale nie usunie zależności.
Suspense, cache i dane dynamiczne w Next.js 16
Samo owinięcie komponentu w <Suspense> nie uruchamia jeszcze automatycznie mechanizmu streamingu, ponieważ granica wyświetli element zastępczy dopiero w momencie, gdy jej potomek faktycznie wstrzyma renderowanie, na przykład oczekując na asynchroniczne pobranie danych. Zwykły komponent synchroniczny zostanie natomiast wyrenderowany od razu w standardowy sposób. Brak domyślnego trwałego cache wyniku fetch nie oznacza jednak, że cała trasa jest renderowana na nowo przy każdym żądaniu. W modelu bez Cache Components trasa może zostać prerenderowana podczas next build. Cache danych i prerenderowanie strony to odrębne mechanizmy; w przykładach cache: 'no-store' jawnie określa pobieranie danych w czasie żądania.
Opis częściowo prerenderowanej powłoki z use cache dotyczy włączonych Cache Components (cacheComponents: true w next.config.ts); nie jest to automatyczny skutek dodania Suspense. W tym trybie stabilne dane lub komponenty można objąć dyrektywą use cache, aby mogły znaleźć się w prerenderowanej powłoce.
Jeżeli używasz Cache Components, dostęp do danych runtime, takich jak cookies(), headers() lub searchParams, powinien znaleźć się pod odpowiednią granicą Suspense. Next.js może wtedy prerenderować zawartość ponad granicą, umieścić fallback w statycznej powłoce i wykonać część zależną od żądania później. Granice umieszczaj możliwie blisko wolnej sekcji, ponieważ zbyt wysoka granica zastąpi fallbackiem również treść, która mogłaby pojawić się od razu.
Błędy i kody HTTP podczas streamingu
Suspense zarządza oczekiwaniem, ale musimy zająć się także obsługą błędów. Dodaj error.tsx w segmentach, w których potrzebujesz osobnego widoku awarii, i loguj błędy po stronie serwera. Taka granica nie obejmuje layoutu z tego samego segmentu; jego błędy obsługuje granica nadrzędna, a błędy głównego layoutu — global-error.tsx.
Podczas SSR komponentów, które mogą wykonać się także w przeglądarce, React potrafi wysłać fallback Suspense po błędzie i ponowić renderowanie na kliencie. Nie oznacza to wykonania Server Component w przeglądarce: błąd jego renderowania trafia do odpowiedniej granicy błędów Next.js, a ponowienie pobrania danych serwerowych wymaga kolejnego żądania do serwera.
Po wysłaniu pierwszego fragmentu odpowiedzi nagłówki są już ostatecznie zatwierdzone, przez co serwer traci możliwość modyfikacji kodu HTTP. Późne wywołanie funkcji notFound() lub redirect() potrafi przekazać odpowiednią instrukcję bezpośrednio w strumieniu, jednak transportowy status odpowiedzi często pozostaje na poziomie 200. Jeśli wymagany jest konkretny status HTTP, kontrola musi nastąpić przed rozpoczęciem odpowiedzi. Przy Cache Components powłoka może zostać wysłana jeszcze przed wykonaniem kodu strony zależnego od żądania, więc samo przeniesienie sprawdzenia na początek page.tsx nie wystarczy. W takim przypadku zaprojektuj kontrolę przed wysłaniem powłoki, np. szybkie sprawdzenie adresu w Proxy, albo osobny Route Handler dla klientów API. Niezależnie od kodu HTTP autoryzację danych wykonuj przed ich pobraniem i ujawnieniem; wysłanie publicznej powłoki nie zastępuje tej kontroli.
Hosting i testowanie streamingu
Na hostingu własnym sprawdź cały łańcuch: serwer Next.js, reverse proxy, load balancer i CDN. Nginx oraz część integracji chmurowych może domyślnie buforować odpowiedź, przez co użytkownik dostanie powłokę i wolną sekcję jednocześnie. Next.js zaleca wyłączenie buforowania, np. nagłówkiem X-Accel-Buffering: no, oraz potwierdzenie obsługi strumieniowania HTTP/2 albo odpowiedzi chunked w HTTP/1.1.
Testuj produkcyjny build, a nie tylko next dev. W DevTools sprawdź timing odpowiedzi i moment pojawienia się kolejnych sekcji; z terminala możesz użyć curl --no-buffer URL, aby obserwować fragmenty bez lokalnego buforowania. Dodaj kontrolowane opóźnienie wyłącznie w środowisku testowym i zweryfikuj osobno czas do powłoki, czas do każdej granicy, CLS oraz zachowanie po błędzie i po przerwaniu nawigacji.


