Next.js i WordPress: integracja treści, podgląd i wdrożenie

Headless WordPress oddziela zarządzanie treścią od jej prezentacji. Panel wp-admin, baza i edytor mogą nadal służyć zespołowi redakcyjnemu, natomiast publiczne strony buduje Next.js. Frontend pobiera dane przez API, a następnie renderuje widoki zgodnie z własną architekturą. WordPress nie przekazuje mu automatycznie całego działania motywu.

W klasycznej witrynie motyw i rozszerzenia współpracują we wspólnym środowisku PHP, często z cache gotowych odpowiedzi. W headless część logiki pozostaje w CMS, lecz formularz, nawigacja, wyszukiwarka lub podgląd wymagają osobnego połączenia. Rozdzielenie aplikacji daje swobodę, ale dodaje miejsca, w których dane mogą się zdezaktualizować albo stać niedostępne.

Zacznij od konkretnej potrzeby: wspólnego CMS dla kilku kanałów, nietypowego interfejsu lub niezależnej pracy zespołu frontendowego. Porównaj ten zakres z poprawą obecnej strony internetowej. Sama nazwa frameworka nie gwarantuje szybkości ani bezpieczeństwa. Jeśli projekt obejmuje sprzedaż, zakres koszyka i płatności rozwija odrębny poradnik headless WooCommerce. Tutaj punktem odniesienia jest publikowanie treści.

Poniższy przebieg dotyczy Next.js 16 z App Router. Przykład pobierania używa Server Component i jawnego no-store; nie korzysta z Cache Components. To prosty punkt startowy do sprawdzenia danych, po którym świadomie projektujesz buforowanie. Istniejący projekt z Pages Router wymaga osobnej adaptacji, a jego funkcji pobierania nie należy mieszać z plikami app.

Dokumentacja instalacji Next.js odczytana 14 września 2026 r. wskazuje minimum Node.js 20.9. Dla nowego wdrożenia wybierz wspieraną gałąź Node zgodną z frameworkiem i hostingiem. Minimalna zgodność nie zastępuje sprawdzenia cyklu utrzymania środowiska. Node nie musi działać na serwerze WordPressa, który nadal wymaga PHP oraz bazy.

Przygotuj repozytorium frontendu, menedżer pakietów, środowisko testowe CMS i dostęp do logów. Zapisz wersje Next.js, React i Node oraz plik blokady zależności. Ustal domenę publiczną, adres CMS i odpowiedzialność za oba środowiska. Osoba pisząca wpisy nie potrzebuje automatycznie dostępu do sekretów aplikacji lub administracji serwerem.

WordPress ma REST API w rdzeniu. Dla wpisów zwykle użyjesz kolekcji wp/v2/posts, lecz dostępność konkretnych typów i pól trzeba sprawdzić. WPGraphQL jest osobnym rozszerzeniem; może odpowiadać projektowi z rozbudowanymi relacjami, ale sama wielkość witryny nie rozstrzyga wyboru. ACF także jest opcją wynikającą z modelu treści.

REST nie wymusza pobierania każdego pola. Dokumentacja parametrów globalnych opisuje _fields oraz _embed. Pierwszy ogranicza odpowiedź, drugi pozwala dołączyć określone zasoby powiązane. Przy ich łączeniu trzeba zachować pola potrzebne do osadzania. GraphQL również wymaga kontroli kosztu zapytania i obsługi błędów, które mogą wystąpić przy statusie HTTP 200.

Spisz kontrakt: identyfikator, slug, tytuł, treść, daty, autor, obraz i relacje. Określ pola wymagane oraz zachowanie przy braku wartości. Dla własnego typu treści sprawdź jego publiczną dostępność i uprawnienia. Lista dozwolonych pól powinna wynikać z potrzeb frontendu, a nie z tego, co da się odczytać kontem administratora.

Najpierw utwórz na kopii reprezentatywny wpis: tekst, nagłówki, obraz, podpis, odnośnik i używany blok. Jeśli projekt wymaga pól dodatkowych, dodaj je do modelu i sprawdź ich rzeczywistą odpowiedź API. Nie instaluj kilku mostów integracyjnych, zanim ustalisz, którego interfejsu będziesz używać.

Sprawdź kolejno publiczny odczyt wpisu, stronicowanie listy, brakujący slug i niedozwolony dostęp do szkicu. Ładne permalinki pomagają organizacji adresów, lecz nie są przełącznikiem aktywującym całe REST API. Reguły serwera, zapora oraz konfiguracja rozszerzeń mogą wpływać na dostęp, dlatego testuj odpowiedź z miejsca uruchomienia frontendu.

Porównaj dane gościa i konta integracyjnego. Uprawnienia tego konta ogranicz do potrzeb procesu, a sekret przechowuj po stronie serwera. Prywatnych treści nie wysyłaj do przeglądarki tylko po to, aby ukryć je komponentem. Obsługa WordPressa powinna obejmować także aktualizacje API i rozszerzeń: zmiana pola lub uprawnień może wpłynąć na aplikację, choć panel redakcyjny nadal działa poprawnie.

Projekt możesz rozpocząć kreatorem create-next-app, wybierając TypeScript i App Router. Przed użyciem kreatora ustal jego wersję oraz docelową gałąź Next.js; po instalacji zweryfikuj package.json i plik blokady. Komenda z latest oznacza wersję bieżącą w chwili uruchomienia, więc nie gwarantuje identycznego projektu w przyszłości.

W .env.local zapisz WP_API_URL wskazujący bazę REST API, na przykład https://cms.example.com/wp-json/wp/v2/. Dla środowiska wdrożeniowego ustaw odpowiednią wartość w zarządzaniu konfiguracją hostingu. Plik z sekretami nie powinien trafić do publicznego repozytorium. Prefiks NEXT_PUBLIC_ udostępnia zmienną kodowi klienta i nie jest miejscem dla hasła aplikacyjnego.

Funkcje pobierania wydziel do modułu serwerowego, na przykład lib/wordpress.ts. Rozdziel odczyt opublikowanego wpisu i uprzywilejowany podgląd. Dzięki temu przegląd kodu pokaże, która ścieżka potrzebuje uwierzytelnienia. Własne automatyzacje publikacji powinny korzystać z tego samego modelu identyfikatorów i statusów, aby aktualizacja nie wskazywała przypadkowej strony.

Poniższy przykład pokazuje odczyt opublikowanego wpisu przez REST API. Działa po stronie serwera i celowo nie dodaje autoryzacji szkiców. Parametry adresu powstają przez URLSearchParams, zamiast przez doklejanie niezweryfikowanej ścieżki. WP_API_URL jest konfiguracją administratora aplikacji, nie wartością przyjmowaną od odwiedzającego.

import 'server-only';

type PublicPost = {
  id: number;
  slug: string;
  title: { rendered: string };
};

export async function getPublicPost(slug: string): Promise<PublicPost | null> {
  const base = process.env.WP_API_URL;
  if (!base) throw new Error('Brak konfiguracji CMS');
  const url = new URL('posts', base.endsWith('/') ? base : `${base}/`);
  url.searchParams.set('slug', slug);
  url.searchParams.set('status', 'publish');
  url.searchParams.set('_fields', 'id,slug,title');

  const response = await fetch(url, { cache: 'no-store' });
  if (!response.ok) throw new Error(`CMS HTTP ${response.status}`);
  const data: unknown = await response.json();
  if (!Array.isArray(data)) throw new Error('Nieprawidłowa odpowiedź CMS');
  if (data.length === 0) return null;
  const post = data[0];
  if (typeof post?.id !== 'number' || typeof post?.slug !== 'string' ||
      typeof post?.title?.rendered !== 'string') {
    throw new Error('Nieprawidłowy format wpisu');
  }
  return post as PublicPost;
}

Null oznacza tu brak opublikowanego wpisu dla slugu, a wyjątek błąd pobrania lub formatu. Strona może zamienić pierwszy przypadek na notFound, natomiast awarię obsłużyć komunikatem i logiem technicznym. Zwracanie pustej tablicy przy każdym błędzie ukryłoby niedostępność CMS jako pusty katalog. W docelowej warstwie dodaj uzgodniony timeout, kontrolę ponawiania i identyfikator błędu bez sekretów.

Opis fetch w Next.js rozróżnia jawne strategie cache. W tym przykładzie no-store służy sprawdzeniu aktualnej odpowiedzi. Nie łącz go z dodatnim revalidate w tej samej konfiguracji. Test produkcyjnego sposobu działania wykonaj także poza trybem deweloperskim, którego mechanizmy odświeżania mogą wpływać na obserwacje.

W App Router pojedynczy artykuł może mieć trasę app/blog/[slug]/page.tsx. Komponent serwerowy odczytuje parametr, pobiera wpis i wybiera widok treści lub brakującej strony. W Next.js 16 parametr params jest asynchroniczny, więc jego odczyt trzeba dopasować do aktualnego interfejsu. Zapis slugu w CMS i adres publiczny frontendu nie muszą być identyczne, jeśli masz świadomą mapę tras.

generateStaticParams pozwala wskazać parametry tras przygotowywane podczas budowania. Sama obecność funkcji nie czyni całej aplikacji statyczną: znaczenie mają pobieranie danych, używane API i konfiguracja. Przykład no-store z poprzedniej sekcji jest punktem do dynamicznego odczytu, a nie kompletną implementacją statycznego eksportu.

Przed zmianą na buforowanie ustal wymagania aktualności. Inaczej może działać publiczne archiwum, inaczej podgląd szkicu. Sprawdź nowy wpis, zmianę slugu, wycofanie publikacji i usunięty materiał. Dla tych przypadków określ status HTTP oraz przekierowanie tam, gdzie ma uzasadnienie. Pusta strona ze statusem 200 utrudni użytkownikowi i robotowi rozpoznanie, co się wydarzyło.

WordPress może zwrócić wyrenderowany HTML treści. React pozwala go wstawić przez dangerouslySetInnerHTML, ale ta operacja nie oczyszcza HTML. Ustal granicę zaufania, dozwolone elementy oraz sposób sanitizacji odpowiedni dla danych i uprawnień redaktorów. Własny CMS nadal może zawierać treść z importu lub dodatku, której nie powinno się wykonywać bez kontroli.

Zapis bloku nie przenosi automatycznie stylów motywu i zachowania rozszerzeń. Sprawdź listy, tabele, podpisy, galerie i elementy interaktywne. Przy wzorcach bloków WordPress ustal, czy frontend korzysta z gotowego HTML, czy mapuje strukturę na komponenty. W obu modelach potrzebujesz próbki rzeczywistej treści, a nie tylko krótkiego akapitu demonstracyjnego.

Dla obrazów z CMS skonfiguruj next/image i remotePatterns możliwie wąsko: protokół, host oraz potrzebna ścieżka. Przy zewnętrznych adresach zapewnij wymiary lub właściwy model fill i sizes. Sprawdź jakość, podpis, alt oraz zachowanie na telefonie. Sposób optymalizacji musi pasować do hostingu; czysty eksport statyczny ma inne możliwości niż aplikacja z działającym serwerem. Samo dodanie domeny do listy nie kończy odbioru zdjęć.

Redaktor potrzebuje obejrzeć szkic bez publikowania go wszystkim. Draft Mode ustawia stan podglądu w aplikacji Next.js. Nie nadaje jednak praw do odczytu prywatnych treści WordPressa i nie pobiera samodzielnie niezapisanej wersji edytora. Ten drugi etap wymaga integracji z właściwym szkicem lub rewizją.

Ustal kontrakt przycisku Podgląd: identyfikator wpisu, oczekiwaną wersję, kontrolowany adres i sposób potwierdzenia uprawnienia. Handler Next.js powinien odrzucić nieprawidłowe żądanie przed włączeniem podglądu. Ścieżkę przekierowania wyznaczaj z dopuszczonych danych CMS, aby parametr użytkownika nie tworzył otwartego przekierowania do obcej domeny.

Uwierzytelniony odczyt szkicu wykonuj na serwerze. Zadbaj, aby jego odpowiedź nie weszła do wspólnego publicznego cache ani sitemap. Dodaj widoczny komunikat o podglądzie i możliwość zakończenia trybu. Test obejmuje redaktora, gościa bez uprawnień, błędny token, inny wpis oraz wyjście z podglądu. Dopiero połączenie tych prób potwierdza, że wygoda redakcji nie ujawnia materiału przed publikacją.

Po sprawdzeniu odczytu wybierz jawnie model buforowania. Publiczne treści mogą korzystać z cache i odświeżania czasowego, jeżeli dopuszczalne opóźnienie odpowiada ich charakterowi. Mechanizm ISR zależy od żądań i konfiguracji; ustawiony okres nie jest harmonogramem przebudowującym wszystkie strony w tle dokładnie w tej samej chwili.

Przy aktualizacji wyzwalanej z CMS przygotuj uwierzytelniony webhook. Zdarzenie powinno identyfikować treść, status i zmianę, a handler mieć ograniczony zakres działania oraz log wyniku. revalidatePath wywołane z Route Handler oznacza ścieżkę do odświeżenia przy kolejnej wizycie. Nie jest potwierdzeniem, że każdy odbiorca już zobaczył nowy HTML.

Uwzględnij zależności: artykuł może pojawiać się w archiwum, kategorii i polecanych materiałach. Zmiana slugu dotyczy także starego adresu. Dobierz invalidację ścieżek lub danych do rzeczywistego modelu, zamiast czyścić wszystko przy każdym zapisie. Odbierz ponowione zdarzenie, awarię CMS i spóźnioną aktualizację. Sekretny endpoint nie powinien przyjmować dowolnej ścieżki do czyszczenia od niezaufanego klienta.

Frontend odpowiada za końcowy tytuł, opis, canonical, adresy i dane strukturalne. Metadane z wtyczki WordPressa mogą być źródłem, jeśli integracja udostępnia potrzebne pola, ale nie pojawią się same w HTML Next.js. Sprawdź pojedynczy wpis i archiwum po stronie publicznej, również przy błędzie pobrania.

Mapa witryny powinna wskazywać właściwe adresy frontendu i aktualny zbiór publikacji. Nie przekazuj bez sprawdzenia mapy CMS, jeśli zawiera domenę zaplecza lub inne ścieżki. Dane strukturalne WordPressa trzeba dopasować do widocznej treści i wyrenderować w docelowym serwisie. Poprawna składnia nie oznacza gwarancji wyniku rozszerzonego.

Przed wdrożeniem ustal obsługę Node, cache, zadań i logów na wybranej platformie. Uruchom build oraz próbę startu z konfiguracją zbliżoną do produkcyjnej. Zabezpiecz kopię CMS, odizoluj formularze i pomiar, a następnie sprawdź publikację, zmianę slugu, wycofanie treści, podgląd i powrót po awarii. Subdomena cms sama nie chroni panelu; potrzebne są właściwe uprawnienia i kontrola dostępu.

Wycena obejmuje model treści, frontend, API, podgląd, aktualizacje i odbiór funkcji. Dochodzi utrzymanie zależności obu aplikacji oraz diagnoza problemów na ich styku. Liczba podstron pomaga opisać projekt, lecz nie wyznacza uniwersalnej granicy opłacalności. Prosty serwis może mieć nietypowy proces redakcyjny, a duża witryna dobrze działać w klasycznej architekturze.

Przed decyzją przygotuj ograniczony prototyp całego procesu: zapis w CMS, podgląd, publikacja i aktualizacja publicznej strony. Oceń koszt odtworzenia formularzy oraz funkcji rozszerzeń. Zapisz także właściciela monitoringu i warunki wycofania wdrożenia. Szybki pierwszy ekran nie wystarczy, jeśli zespół nie potrafi bezpiecznie zmienić opublikowanej treści.

Przez kontakt KC Mobile opisz obecny CMS, potrzebne kanały i trudności w pracy redaktorów. Na tej podstawie można ustalić zakres integracji albo poprawy obecnej strony. Po wdrożeniu możliwe jest wsparcie w małych pakietach godzinowych; czynności, dostępność oraz ewentualne SLA ustalamy indywidualnie, wraz z odpowiedzialnością za WordPressa i aplikację Next.js.