Integracja Next.js z WordPress – krok po kroku

Headless WordPress to taki sposób użycia WordPressa, w którym oddzielasz warstwę zarządzania treścią (panel wp-admin, baza danych, edytor) od warstwy prezentacji, czyli tego, co widzi użytkownik w przeglądarce. W klasycznej instalacji WordPress sam generuje gotowy HTML przy użyciu motywu (PHP). W modelu headless WordPress staje się wyłącznie backendem – odpowiada za przechowywanie wpisów, stron, mediów i pól dodatkowych, a oddaje je w postaci czystych danych przez API.

Frontend buduje wtedy osobna aplikacja Next.js (framework oparty na React). Komunikacja przebiega tak: Next.js wysyła zapytanie do endpointu WordPressa (REST API lub GraphQL), dostaje dane w formacie JSON i renderuje z nich strony. Redaktor dalej pisze wpisy w znajomym wp-adminie, a odwiedzający trafia na szybką, statycznie wygenerowaną witrynę. To rozdzielenie nazywa się architekturą zdekuplowaną (decoupled).

Taki układ daje swobodę: ten sam backend WordPress może zasilać stronę WWW, aplikację mobilną i panel partnera jednocześnie.

Najprościej widać różnicę na osi monolit kontra architektura zdekuplowana.

WordPress klasyczny (monolit):
- Backend i frontend to jedna aplikacja PHP.
- Motyw renderuje HTML po stronie serwera przy każdym żądaniu.
- Wtyczki (np. formularze, SEO, sklep) działają bez dodatkowej integracji.
- Łatwy start, niski koszt, ogromna baza gotowych rozwiązań.

WordPress headless (zdekuplowany):
- Backend (WordPress) oddaje dane przez API, frontend (Next.js) je konsumuje.
- Strony są generowane statycznie lub renderowane po stronie serwera Node.js.
- Część wtyczek front-endowych przestaje działać, bo nie ma motywu PHP.
- Wyższa wydajność i bezpieczeństwo, ale większa złożoność i koszt wdrożenia.

W skrócie: monolit wybierasz dla prostoty i szybkiego startu, headless – gdy zależy Ci na maksymalnej szybkości, skali i nowoczesnym froncie. Jeśli planujesz nową witrynę firmową, warto najpierw zajrzeć do oferty stron internetowych i ocenić, czy headless w ogóle Ci się opłaca.

Zanim napiszesz pierwszą linijkę kodu, przygotuj środowisko. Lista wymagań wstępnych dla integracji headless WordPress z Next.js:

• Działająca instancja WordPress – lokalnie (np. przez Local, XAMPP, Docker) albo na serwerze. Zalecana wersja WordPress 6.x lub nowsza, bo starsze wydania mają słabsze REST API.
• Node.js w wersji 18.17 lub nowszej – Next.js (zwłaszcza wersje 14 i 15) wymaga nowoczesnego środowiska. Sprawdzisz to komendą `node -v`.
• Menedżer pakietów – npm (idzie z Node.js), opcjonalnie pnpm lub yarn.
• Podstawy React i JavaScriptu – komponenty, props, async/await, fetch. Bez tego kod Next.js będzie trudny do utrzymania.
• Dostęp do panelu wp-admin z prawami administratora (instalacja wtyczek, zmiana permalinków).
• Edytor kodu (np. VS Code) i terminal.

Jeśli nie masz technicznego zaplecza, to jest moment, w którym wiele firm decyduje się oddać projekt agencji. Lepiej zacząć z dobrym fundamentem niż naprawiać chaos później.

WordPress udostępnia treści na dwa popularne sposoby. Wybór wpływa na cały dalszy kod.

Wbudowane REST API – działa od razu, bez wtyczek, pod adresem `/wp-json/wp/v2/`. Zaletą jest zero konfiguracji i prostota. Wadą – tzw. over-fetching: pobierasz całe obiekty wpisów, nawet jeśli potrzebujesz tylko tytułu i fragmentu. Przy dużych stronach generuje to nadmiarowy transfer i więcej zapytań.

WPGraphQL (wtyczka) – udostępnia jeden endpoint GraphQL, w którym precyzyjnie określasz, jakie pola chcesz dostać. Jedno zapytanie potrafi pobrać wpis, jego autora, kategorie i pola ACF naraz. To rozwiązuje over-fetching i upraszcza front.

Kiedy co wybrać:
- REST API – mały projekt, prototyp, prosta lista wpisów, brak rozbudowanych pól.
- WPGraphQL – większa witryna, wiele typów treści, pola dodatkowe ACF, zależy Ci na wydajności zapytań.

Dla produkcyjnych wdrożeń headless w praktyce wygrywa WPGraphQL – mniej zapytań, czytelniejszy kod, lepsza kontrola.

Backend trzeba przygotować, zanim front cokolwiek pobierze. Przejdź te kroki w wp-adminie:

1. Włącz ładne permalinki – wejdź w Ustawienia → Bezpośrednie odnośniki i wybierz np. opcję Nazwa wpisu. To aktywuje pełne, czytelne adresy i poprawnie działające REST API.
2. Zainstaluj WPGraphQL – z repozytorium wtyczek (Wtyczki → Dodaj nową, szukaj WPGraphQL). Po aktywacji pojawi się endpoint `/graphql` oraz wbudowany IDE do testowania zapytań.
3. Zainstaluj ACF (Advanced Custom Fields) – jeśli potrzebujesz pól dodatkowych, np. cena, wyróżnik, dane kontaktowe. ACF pozwala rozszerzyć wpisy o własne dane.
4. Dodaj WPGraphQL for ACF – ten most sprawia, że pola ACF stają się dostępne w zapytaniach GraphQL. Bez niego ACF nie pojawi się w schemacie.
5. Zdefiniuj pola dodatkowe w ACF i przypisz je do typów wpisów. Zaznacz opcję udostępniania w GraphQL.
6. Sprawdź dostępność z zewnątrz – upewnij się, że endpoint odpowiada (otwórz `https://twojadomena.pl/graphql` lub `/wp-json/`).

Po tych krokach WordPress jest gotowym, headlessowym źródłem danych. Jeśli na tym etapie coś nie działa, pomocne bywa wsparcie kogoś, kto na co dzień zajmuje się WordPressem.

Front zaczynasz od jednej komendy w terminalu:

`npx create-next-app@latest moj-projekt`

Kreator zapyta o TypeScript, ESLint i App Router – dla nowych projektów wybierz App Router, bo to obecny standard z routingiem opartym na plikach (każdy folder w `app/` to ścieżka URL).

Zmienne środowiskowe. Utwórz plik `.env.local` w katalogu projektu i zapisz adres endpointu, np.:

`WP_API_URL=https://twojadomena.pl/graphql`

Dzięki temu nie zaszywasz adresu na sztywno w kodzie i łatwo przełączysz środowisko lokalne na produkcyjne.

Pobieranie danych. Do REST API wystarczy wbudowany `fetch`. Do GraphQL wygodna jest biblioteka `graphql-request`. Przykładowy schemat: wysyłasz zapytanie o listę wpisów (tytuł, slug, fragment, data), odbierasz JSON, obsługujesz ewentualny błąd odpowiedzi i przekazujesz dane do komponentu. Zawsze sprawdzaj status odpowiedzi i zabezpiecz front na wypadek, gdy WordPress jest chwilowo niedostępny – pusta tablica zamiast błędu psującego całą stronę.

Dobrą praktyką jest wydzielenie funkcji pobierających dane do osobnego pliku (np. `lib/api.js`), żeby nie powtarzać kodu.

Sercem wydajności Next.js jest generowanie stron statycznych (SSG). Przy App Router używasz funkcji `generateStaticParams`, która zwraca listę slugów wszystkich wpisów. Next.js buduje wtedy osobny plik HTML dla każdego artykułu już na etapie kompilacji. W starszym Pages Router odpowiednikiem są `getStaticPaths` i `getStaticProps`. Efekt: dynamiczny routing (strony pojedynczych wpisów pod `/blog/[slug]`) przy statycznej, błyskawicznej obsłudze.

Renderowanie treści Gutenberga. WordPress oddaje treść wpisu jako gotowy HTML (bloki Gutenberga). Wstawiasz go w React przez `dangerouslySetInnerHTML`. Nazwa brzmi groźnie i słusznie – ufaj tylko treści z własnego, zaufanego WordPressa, bo wstrzykiwany HTML to potencjalny wektor ataku XSS.

Optymalizacja obrazów. Media z `wp-content` wyświetlaj komponentem `next/image`, który automatycznie skaluje i serwuje nowoczesne formaty. Tu częsty błąd wdrożeniowy: trzeba dodać domenę WordPressa do `remotePatterns` w pliku `next.config.js`, inaczej Next.js zablokuje zewnętrzne obrazy i dostaniesz błąd. Po skonfigurowaniu zyskujesz lekkie, responsywne grafiki bez ręcznej obróbki.

Największy praktyczny problem headless: skoro strony są statyczne, jak je odświeżyć po edycji w wp-adminie? Naiwne rozwiązanie (przebudowa całej strony po każdej zmianie) jest wolne i kosztowne.

ISR (Incremental Static Regeneration) to mechanizm Next.js, który pozwala odświeżać pojedyncze strony w tle. Ustawiasz parametr rewalidacji (np. co 60 sekund) i Next.js sam regeneruje stronę po upływie tego czasu, gdy ktoś ją odwiedzi. Treść jest świeża, a serwer nie przebudowuje wszystkiego naraz.

On-demand revalidation z webhookami to wersja precyzyjna. Konfigurujesz w WordPressie webhook, który po zapisaniu wpisu wysyła sygnał do endpointu Next.js (np. `/api/revalidate`). Ten wywołuje `revalidatePath` lub `revalidateTag` i odświeża dokładnie tę jedną stronę, która się zmieniła. Efekt: redaktor klika Zaktualizuj w wp-adminie, a zmiana pojawia się na produkcji w kilka sekund, bez pełnego deploya. To rozwiązuje problem unieważniania cache (cache invalidation) i jest standardem w dojrzałych wdrożeniach.

SEO w headless wymaga świadomej pracy, bo tracisz automatykę motywu WordPress. Co trzeba zaimplementować ręcznie:

• Meta tagi – tytuł i opis pobieraj z WordPressa. Jeśli używasz Yoast SEO lub Rank Math, ich dane wyciągniesz przez API (Yoast SEO ma dodatek do WPGraphQL) i wstawisz w `metadata` Next.js.
• Sitemap.xml – wygeneruj go w Next.js, np. biblioteką `next-sitemap`, albo proxy do mapy z WordPressa. Statyczny sitemap motywu nie zadziała w headless.
• Dane strukturalne (JSON-LD: Article, BreadcrumbList) dodaj w komponencie strony, by zwiększyć szansę na rich results.
• Tagi canonical ustaw świadomie, żeby nie tworzyć duplikatów między domeną backendu a frontendu.
• Szybkość – statyczny front Next.js to świetne Core Web Vitals, a te realnie wpływają na pozycje w Google.

Tryb podglądu (preview mode) rozwiązuje kluczowy problem redaktora: jak zobaczyć draft przed publikacją, skoro strona jest statyczna? Next.js ma wbudowany Draft Mode – specjalny endpoint przełącza wybranego użytkownika w tryb renderowania na żywo, pobierając niezapisaną wersję z WordPressa. Redaktor klika Podgląd w wp-adminie i widzi szkic dokładnie tak, jak będzie wyglądał. Bez tego praca redakcyjna w headless jest mocno utrudniona – dlatego warto to wdrożyć od początku.

Korzyści biznesowe:
- Wydajność – statyczne strony ładują się błyskawicznie, co poprawia konwersję i SEO.
- Bezpieczeństwo dzięki separacji warstw – wp-admin można ukryć lub odciąć od publicznego internetu, więc typowe ataki na WordPressa mają mniejszą powierzchnię.
- Skalowalność – statyczny front wytrzymuje skoki ruchu bez obciążania bazy.
- Znane środowisko dla zespołu – redaktorzy zostają w wygodnym wp-adminie, a deweloperzy pracują w nowoczesnym React.

Wady i wyzwania:
- Koszty – wdrożenie headless jest droższe niż klasyczny WordPress: to praca dewelopera, dwa środowiska hostingowe i utrzymanie.
- Kompetencje techniczne – potrzebujesz kogoś, kto zna React, Next.js i API. To nie jest projekt dla osoby nietechnicznej.
- Kompatybilność wtyczek – wiele wtyczek front-endowych (formularze, popupy, niektóre SEO) przestaje działać i trzeba je odtworzyć w Next.js.

Kiedy NIE wybierać headless: mała strona firmowa lub wizytówka, ograniczony budżet, brak zaplecza technicznego, silna zależność od gotowych wtyczek. Dla typowej witryny MŚP klasyczny WordPress z dobrym cachingiem zwykle wystarcza i kosztuje mniej. Mówiąc wprost: jeśli prowadzisz lokalny biznes z 10 podstronami, headless to przerost formy nad treścią. Zacznij od zwykłej strony internetowej, a headless rozważ dopiero przy dużym ruchu lub wielu kanałach.

Deployment w headless dotyczy dwóch osobnych elementów:

• Frontend Next.js – hostujesz na platformie wspierającej Node.js i ISR. Popularne wybory to Vercel (twórcy Next.js), Netlify albo własny serwer Node z VPS. Tu trafia kod, zmienne środowiskowe i webhooki rewalidacji.
• Backend WordPress – zostaje na klasycznym hostingu PHP/MySQL. Warto wybrać solidnego polskiego dostawcę, np. CyberFolks{rel=noopener sponsored}, LH.pl lub Zenbox. Backend może być ukryty za subdomeną (np. `cms.twojadomena.pl`), a publiczna domena wskazuje na front Next.js.

Koszt wdrożenia. Headless to projekt indywidualny, więc cena zależy od liczby typów treści, integracji i podglądu. Dla porównania skali: u nas zwykła strona startuje od 3000 zł, sklep WooCommerce od 8000 zł, a opieka techniczna od 299 zł/mies. Wdrożenie headless z Next.js jest bardziej złożone niż standardowa strona, więc realnie wyceniamy je wyżej i zawsze po analizie potrzeb. Jeśli zastanawiasz się, czy headless się Tobie opłaca, czy wystarczy klasyczny WordPress, napisz do nas – doradzimy uczciwie, bo nie każdemu headless się zwraca.