Szybka odpowiedź: jak działa Partial Prerendering w Next.js?
- PPR łączy prerenderowaną powłokę z dynamicznymi fragmentami dosyłanymi strumieniowo.
- Dane współdzielone cache'ujesz przez
"use cache", a fragmenty zależne od żądania umieszczasz w<Suspense>. - Dynamiczne są też każdy niecache'owany
fetchi zapytanie do bazy, nie tylkocookies()czyheaders(). - W Next.js 16 PPR to część Cache Components włączanych przez
cacheComponents, aexperimental.pprusunięto. - Najwięcej daje na stronach w większości statycznych z niewielką personalizacją, np. kartach produktów.
Czym jest Partial Prerendering w Next.js?
Partial Prerendering (PPR) to model renderowania w Next.js, który pozwala na jednej stronie łączyć elementy statyczne (generowane podczas buildu) z elementami dynamicznymi (renderowanymi na żądanie).
W modelach / przygotowujemy dokument wcześniej, a renderuje go na żądanie i może przy tym korzystać z cache danych oraz strumieniowania. PPR łączy wcześniej przygotowaną powłokę z renderowaniem części treści na żądanie: prerenderowana powłoka strony jest wysyłana bez oczekiwania na dynamiczne „wyspy”, które są w tle. Dostarczenie powłoki bezpośrednio z jest optymalizacją infrastruktury.
W starszych wersjach Next.js PPR było pokazywane jako osobna, eksperymentalna funkcja, ale w aktualnych wersjach ten sam kierunek rozwija się pod nazwą Cache Components i opiera się na cacheComponents, dyrektywie "use cache" oraz Suspense.
Innymi słowy, zmienia się poziom decyzji, ponieważ teraz nie wybieramy już renderowania dla całej strony. Wybieramy go dla konkretnych komponentów.
Jak PPR działa pod maską w Next.js?
PPR opiera się na trzech mechanizmach:
-
Statyczna powłoka, czyli layout, nagłówek, nawigacja, stopka, elementy zastępcze (ang. fallback) i treści, które można ukończyć podczas prerenderowania. Powłoka może być obsłużona przez serwer źródłowy (origin) albo, przy odpowiedniej integracji platformy, z CDN.
-
Dynamiczne wyspy (holes). Fragmenty pod
<Suspense>, które wymagają danych zależnych od żądania albo niecache'owanego I/O. Samo<Suspense>nie czyni synchronicznego komponentu dynamicznym. -
Strumieniowanie. Dynamiczne wyspy są renderowane na serwerze przy każdym żądaniu i przesyłane strumieniowo do przeglądarki, wypełniając „dziury” w statycznej powłoce.
Jak włączyć Partial Prerendering w Next.js?
W aktualnych wydaniach Next.js 16 nowe projekty App Routera tworzone z rekomendowanymi ustawieniami create-next-app mają już Cache Components i Partial Prefetching. W istniejącym projekcie konfiguracja wygląda tak:
Partial Prefetching dotyczy częściowego pobierania tras przed nawigacją i nie jest inną nazwą PPR. Aktualna dokumentacja konfiguracji zaleca jawne ustawienie tej opcji; jej pominięcie powoduje ostrzeżenie. Wartość false służy przejściowej migracji projektów używających wcześniejszej wersji Cache Components.
W starszych materiałach zobaczysz jeszcze experimental.ppr = 'incremental' i export const experimental_ppr = true. Aktualnie praktycznym punktem odniesienia są cacheComponents, "use cache" i Suspense.
Oznaczanie strony jako PPR
W tym modelu nie oznaczasz już całej strony pojedynczą flagą dla danej ścieżki, ale cache'ujesz wybrane fragmenty za pomocą dyrektywy "use cache", a operacje oraz dane zależne od czasu żądania umieszczasz wewnątrz komponentów <Suspense>. Oznaczenia takie jak „statyczne” w przykładowym kodzie zakładają, że dany element wykonuje wyłącznie zadania możliwe do zrealizowania podczas wstępnego prerenderowania lub sam korzysta z cache'owania. Funkcja generateStaticParams() wskazuje parametry znane podczas buildu: użyj rzeczywistych identyfikatorów produktów. Przy Cache Components musi zwrócić co najmniej jeden zestaw parametrów. Pozostałe ścieżki wymagają obsługi parametrów w czasie żądania i odpowiedniej granicy Suspense, np. w nadrzędnym layoucie; nie otrzymują podczas buildu tej samej gotowej treści produktu. Pokazane komponenty UI i adresy API są schematem do uzupełnienia w aplikacji. Zobacz zasady generateStaticParams.
Co sprawia, że komponent w PPR jest dynamiczny?
Next.js automatycznie wykrywa, które komponenty są dynamiczne na podstawie użycia API zależnych od żądania:
Funkcja getVerifiedPricingSegment to funkcja pomocnicza w Twojej aplikacji, a nie wbudowane API Next.js. Gdy sesja nie istnieje lub wygasła, zwraca ona segment standardowy, a ewentualny rabat wylicza wyłącznie na podstawie uprawnień zapisanych po stronie serwera. Nigdy nie ufaj wartości segment odczytanej bezpośrednio z ciasteczka. Endpoint zwracający cennik musi blokować możliwość samodzielnego narzucenia grupy cenowej przez klienta, a podczas finalizacji zamówienia serwer powinien ponownie przeliczyć ostateczną kwotę.
Przy włączonych Cache Components zwykłe asynchroniczne I/O nie trafia automatycznie do prerenderowanej powłoki (fetch, zapytanie ORM czy odczyt pliku). W sytuacji, gdy dane mają być świeże przy każdym żądaniu, umieść pracę pod <Suspense>, a gdy mają być współdzielone i okresowo odświeżane, użyj "use cache" z cacheLife i ewentualnie cacheTag. Żądania API, takie jak odczyt cookies() czy headers(), wykonuj poza zakresem objętym cache'owaniem, a wybrane wartości przekaż do funkcji cache'owanej jako argumenty, aby świadomie kontrolować strukturę klucza cache.
Rewalidacja cache'owanych fragmentów
Wywołanie cacheLife('hours') definiuje czas życia pamięci podręcznej, natomiast cacheTag z identyfikatorem konkretnego produktu pozwala unieważnić wyłącznie jego wpis po aktualizacji danych. Wewnątrz Server Action sięgnij po updateTag(tag), jeśli użytkownik musi od razu zobaczyć efekt swojej zmiany. Z kolei w webhookach oraz wszędzie tam, gdzie dopuszczasz model stale-while-revalidate, lepiej sprawdzi się revalidateTag(tag, 'max'). Bez przemyślanej strategii odświeżania nawet błyskawiczna warstwa prezentacji zacznie pokazywać nieaktualne ceny lub stany magazynowe.
Standardowa dyrektywa "use cache" nie wystawia wyniku publicznie sama z siebie. Klucz pamięci podręcznej jest budowany na podstawie przekazanych argumentów oraz wartości przechwyconych z domknięcia funkcji. Jeśli cache'ujesz dane powiązane z konkretnym kontem, zawsze weryfikuj uprawnienia przed zwróceniem wyniku i upewnij się, że w kluczu cache znajduje się identyfikator użytkownika lub organizacji. Błędnie skonstruowany klucz grozi wyciekiem prywatnych informacji między różnymi odbiorcami.
Dyrektywa "use cache: private" pozwala czytać cookies(), headers() i inne dane żądania wewnątrz cache'owanej funkcji. W aktualnej dokumentacji nie jest oznaczona jako eksperymentalna. Na produkcji wynik może być ponownie użyty w obrębie jednego żądania, ale nie jest przechowywany w serwerowym cache między żądaniami. W trybie deweloperskim działa cache w pamięci z kluczem zależnym od cookies i nagłówków. Router klienta może zachować wynik w pamięci przeglądarki przez czas stale ustawiony w cacheLife; odświeżenie strony go usuwa. Funkcja nadal wykonuje się w czasie żądania i nie trafia do statycznej powłoki.
PPR w praktyce na stronie e-commerce
Najlepszym przykładem wartości PPR jest strona produktowa w sklepie internetowym.
Bez PPR: cała strona może czekać na zakończenie procesu SSR, jeśli spersonalizowana cena oraz stan koszyka są odczytywane przed wyrenderowaniem odpowiedzi. Rzeczywisty wskaźnik TTFB zależy bezpośrednio od hostingu, regionu oraz wydajności źródeł danych, dlatego też nie istnieje jeden uniwersalny zakres czasowy dla renderowania serwerowego.
Z PPR: wstępna powłoka obejmująca układ strony, opis produktu, specyfikację oraz odpowiednie elementy zastępcze może zostać wysłana do klienta jeszcze przed obliczeniem ceny i zawartości koszyka. To, czy strona serwowana jest bezpośrednio z CDN i jak szybko dociera do użytkownika, pozostaje uzależnione od specyfiki wdrożenia.
Właściwość dangerouslySetInnerHTML jest bezpieczna wyłącznie wtedy, gdy renderowany kod HTML został wcześniej dokładnie oczyszczony po stronie serwera lub pochodzi z bezwzględnie zaufanego źródła. Nigdy nie używaj tego rozwiązania do wyświetlania surowej treści od użytkowników ani niezweryfikowanych odpowiedzi z systemów CMS. Z kolei komponent ProductReviews stanie się elementem zależnym od czasu żądania tylko wtedy, gdy faktycznie wykona operację bez cache'owania lub skorzysta z danych żądania, ponieważ sama obecność granicy <Suspense> nie wymusza takiego zachowania.
PPR a SEO i Core Web Vitals
PPR może wspierać SEO i wydajność z kilku powodów:
Szybszy TTFB dzięki statycznej powłoce
Prerenderowana powłoka może obniżyć TTFB i szybciej pokazać użyteczną część dokumentu, ale sam TTFB jest metryką diagnostyczną, a nie jednym z trzech Core Web Vitals. Wpływ PPR trzeba zmierzyć na realnym wdrożeniu.
Krytyczna treść dostępna w powłoce
Robot wyszukiwarki może zobaczyć prerenderowaną powłokę przed ukończeniem dynamicznych fragmentów, których odbiór zależy od czasu odpowiedzi i procesu renderowania. W związku z tym krytyczne elementy SEO, takie jak H1, wstęp, opis produktu i główna treść, najlepiej utrzymywać w powłoce, a nie odkładać ich do komponentów przesyłanych strumieniowo z opóźnieniem.
Lepszy LCP dzięki Partial Prerendering
Jeżeli kandydat LCP (np. hero albo zdjęcie produktu) znajduje się w powłoce i jego zasób jest poprawnie priorytetyzowany, może pojawić się bez czekania na dynamiczne dane. PPR może więc poprawić , ale nie gwarantuje dobrego wyniku, ponieważ nadal liczą się rozmiar obrazu, CSS, fonty, połączenie użytkownika i obciążenie głównego wątku.
Ograniczenia Partial Prerendering
Ewolucja API PPR od eksperymentu do stabilności
To obszar, który szybko się rozwijał, więc łatwo trafić na nieaktualne materiały. Wczesna flaga experimental.ppr i konfiguracja trasy experimental_ppr zostały usunięte na rzecz Cache Components. W Next.js 16 cacheComponents jest konfiguracją najwyższego poziomu, a "use cache", cacheLife i cacheTag są dostępne bez prefiksu unstable_. unstable_cache należy do poprzedniego modelu cache i nie jest tym samym API co "use cache"; przy migracji korzystaj z przewodnika dla Cache Components zamiast mechanicznie zamieniać nazwy.
PPR wymaga granic Suspense
Każdy fragment z niecache'owanym I/O lub danymi czasu żądania potrzebuje nadrzędnego <Suspense>. Jeśli go brakuje, przy cacheComponents: true Next.js zgłosi błąd Uncached data was accessed outside of <Suspense> w trybie deweloperskim lub podczas buildu i nie przełączy po cichu całej strony na SSR. Granicę umieszczaj możliwie blisko dynamicznego fragmentu, aby jego oczekiwanie nie zastępowało dużej części interfejsu elementem zastępczym. Samo <Suspense> nie wyklucza zawartości z prerenderowania: statyczne i cache’owane komponenty mogą zostać ukończone wcześniej, a element zastępczy pojawia się tam, gdzie renderowanie się zawiesza.
Element zastępczy <Suspense> nie obsługuje błędów, tylko stan oczekiwania, więc dla dynamicznej wyspy zaplanuj również granicę błędów (Error Boundary), np. error.tsx na poziomie trasy, i obserwowanie po stronie serwera. Plik error.tsx na poziomie trasy obejmuje cały segment trasy, więc nie gwarantuje izolacji pojedynczej wyspy. Zakres kontrolowanego komunikatu o błędzie zależy od umiejscowienia granicy błędów.
PPR wymaga platformy ze strumieniowaniem
PPR działa na pojedynczym serwerze next start i w kontenerze Docker. Korzyść z progresywnego dostarczania wymaga strumieniowania na całej ścieżce: load balancer, CDN i reverse proxy nie mogą buforować odpowiedzi. Bez tego wynik może pozostać funkcjonalnie poprawny, ale powłoka i dynamiczna treść dotrą razem. Przy wielu instancjach potrzebujesz również współdzielonego cache i koordynacji tagów, jeśli oczekujesz spójnej rewalidacji. output: 'export' nie obsługuje Cache Components.
Debugowanie Partial Prerendering
Ustalenie, które komponenty są statyczne, a które dynamiczne, może nie być takie oczywiste. W trybie deweloperskim Next.js pokazuje wskaźnik statycznej trasy (Static Indicator), ale w złożonych drzewach komponentów zależności bywają trudne do wyśledzenia.
Nie opieraj diagnostyki na dawnym symbolu ◐, ponieważ aktualny wynik w CLI rozróżnia przede wszystkim trasy statyczne (○) i dynamiczne (ƒ). Aby sprawdzić, co faktycznie weszło do powłoki PPR, sprawdź początkową porcję odpowiedzi i elementy zastępcze oraz kolejność dostarczania kolejnych fragmentów. Pełne źródło HTML może już zawierać treść dosłaną strumieniowo, więc nie pokazuje wyłącznie powłoki. Zachowanie strumieniowania przetestuj po produkcyjnym buildzie na docelowej infrastrukturze z wyłączonym buforowaniem proxy.
PPR vs SSR, SSG i ISR w Next.js
| Model | Generowanie | Personalizacja | Charakterystyka odpowiedzi | Użycie |
|---|---|---|---|---|
| SSG | Podczas buildu | Brak w HTML | Gotowy dokument bez pracy renderera na żądanie | Blogi, dokumentacja, strony docelowe |
| ISR | Prerender + rewalidacja | Brak w cache | Gotowy dokument okresowo odświeżany | Produkty, artykuły z CMS |
| SSR | Renderowanie na każde żądanie | Pełna | TTFB zależy od całej pracy blokującej odpowiedź | Pulpity, panele administracyjne |
| PPR | Powłoka + fragmenty z czasu żądania | Częściowa | Powłoka może dotrzeć przed dynamicznymi fragmentami | E-commerce, strony z personalizacją |
PPR nie zastępuje SSG ani ISR, ale je uzupełnia. Strona czysto statyczna (blog, dokumentacja) nie potrzebuje PPR. Dobrym kandydatem jest strona z dużą częścią statyczną i wydzieloną personalizacją; nie istnieje wymagana proporcja 80/20.
Jak przygotować projekt Next.js na PPR?
Nawet jeśli nie włączysz PPR dzisiaj, możesz przygotować architekturę:
- Oddzielaj komponenty statyczne od dynamicznych. Nie mieszaj
cookies()i statycznych danych w jednym komponencie. - Używaj Suspense celowo. Otaczaj nim niecache'owane I/O i dane zależne od żądania, a nie każdy komponent z danymi.
- Cache'uj świadomie. Współdzielone dane, dla których akceptujesz nieaktualność, oznaczaj
"use cache"i dobierajcacheLifeorazcacheTag. - Przenoś dynamiczne API do dedykowanych komponentów.
cookies()iheaders()umieszczaj możliwie blisko fragmentów, które ich potrzebują. Liście drzewa to wygodny wzorzec, a nie wymóg Next.js.
Te praktyki ułatwiają wdrożenie Cache Components, ale nie zastępują pomiaru wydajności, strategii rewalidacji ani testu hostingu pod kątem strumieniowania.


