WordPress jako headless CMS – jak działa, kiedy warto i jak zacząć

WordPress jako headless CMS oznacza, że używasz go tylko jako zaplecza do pisania i organizowania treści, a stronę dla odwiedzających buduje osobna aplikacja – na przykład w Next.js, Astro czy Nuxt – która pobiera dane przez REST API albo GraphQL. Redaktorzy pracują w znanym panelu WordPressa, a programiści mają pełną swobodę w wyborze technologii frontendu.

To podejście daje wydajność, bezpieczeństwo i elastyczność, ale kosztuje: tracisz część wtyczek, podgląd szkiców wymaga dodatkowej pracy, a utrzymujesz dwa systemy zamiast jednego. Poniżej wyjaśniam, jak to działa technicznie, co trzeba rozwiązać i kiedy headless się opłaca.

Czym jest headless CMS i czym różni się od klasycznego WordPressa

W klasycznym WordPressie jedna aplikacja PHP robi wszystko: przechowuje treści, obsługuje panel administracyjny i generuje HTML za pomocą motywu. Każde wejście na stronę (bez cache) uruchamia PHP i zapytania do bazy danych.

Headless CMS „odcina głowę”, czyli warstwę prezentacji. CMS udostępnia treści przez API, a ich wyświetlaniem zajmuje się dowolny klient: strona WWW, aplikacja mobilna, aplikacja na telewizor czy kiosk informacyjny.

Model decoupled jest pośredni: WordPress nadal wyświetla stronę główną motywem, ale udostępnia też treści np. aplikacji mobilnej. W praktyce te pojęcia często się miesza.

REST API WordPressa – podstawa trybu headless

Od wersji 4.7 WordPress ma wbudowane REST API. Działa od razu, bez wtyczek:

# Ostatnie wpisy, tylko wybrane pola
curl "https://cms.example.pl/wp-json/wp/v2/posts?per_page=5&_fields=id,slug,title,date"

# Wpis po slugu, z osadzonym obrazkiem wyróżniającym i autorem
curl "https://cms.example.pl/wp-json/wp/v2/posts?slug=moj-wpis&_embed"

# Strony, kategorie, media
curl "https://cms.example.pl/wp-json/wp/v2/pages"
curl "https://cms.example.pl/wp-json/wp/v2/categories"

Kilka rzeczy, które warto wiedzieć:

• domyślnie zwracanych jest 10 elementów, maksymalnie 100 na stronę (per_page); łączną liczbę wyników i stron podają nagłówki X-WP-Total i X-WP-TotalPages,
• parametr _embed dołącza powiązane dane (autor, obrazek, kategorie), a _fields ogranicza odpowiedź do potrzebnych pól,
• własne typy treści muszą mieć ustawione 'show_in_rest' => true w register_post_type(), a pola ACF – włączoną opcję udostępniania w REST API,
• zapis treści przez API wymaga uwierzytelnienia; najprościej przez hasła aplikacji (Użytkownicy → Profil → Hasła aplikacji), dostępne od WordPressa 5.6.

Jeśli dopiero poznajesz same API, zacznij od artykułu REST API – jak zacząć, a o polach niestandardowych przeczytasz w poradniku o ACF w WordPressie.

WPGraphQL – gdy REST API nie wystarcza

Przy rozbudowanym modelu treści REST API zaczyna być niewygodne: do zbudowania jednej strony potrzebujesz kilku zapytań, a odpowiedzi zawierają mnóstwo zbędnych pól. Wtyczka WPGraphQL dodaje endpoint /graphql, w którym pytasz dokładnie o to, czego potrzebujesz:

query OstatnieWpisy {
  posts(first: 10) {
    nodes {
      title
      slug
      date
      excerpt
      featuredImage {
        node {
          sourceUrl
          altText
        }
      }
      categories {
        nodes {
          name
          slug
        }
      }
    }
  }
}

WPGraphQL ma rozszerzenia dla ACF, Yoast SEO i WooCommerce, a w 2024 r. ogłoszono, że stanie się wtyczką kanoniczną projektu WordPress, co dobrze wróży jej utrzymaniu.

Frontend: Next.js, Astro, Nuxt i inne

Frontend może być napisany w czymkolwiek, co potrafi wykonać zapytanie HTTP. Najczęściej wybierane:

• Next.js (React) – największy ekosystem; WP Engine rozwija framework Faust.js, który ułatwia m.in. podgląd szkiców i uwierzytelnianie,
• Astro – generuje szybkie strony statyczne z minimalną ilością JavaScriptu, świetny do blogów i serwisów treściowych,
• Nuxt (Vue) i SvelteKit – odpowiedniki Next.js w innych ekosystemach.

Przykład w Astro – lista wpisów pobrana podczas budowania strony:

---
const res = await fetch('https://cms.example.pl/wp-json/wp/v2/posts?per_page=10&_fields=slug,title');
const posts = await res.json();
---
<ul>
  {posts.map((post) => (
    <li><a href={`/${post.slug}/`} set:html={post.title.rendered} /></li>
  ))}
</ul>

Treść wpisu z REST API (content.rendered) to gotowy HTML wygenerowany z bloków Gutenberga. Możesz go wstawić bezpośrednio, ale musisz wtedy dostarczyć style bloków. Bardziej zaawansowane projekty parsują bloki i mapują je na własne komponenty. Jak działają same bloki, wyjaśniamy w poradniku o edytorze Gutenberg.

Statycznie czy dynamicznie?

Masz trzy główne strategie renderowania:

1. SSG (generowanie statyczne) – cała strona budowana jest z góry; najszybsza i najtańsza w hostingu, ale każda zmiana treści wymaga przebudowania.
2. SSR (renderowanie na serwerze) – strona generowana przy każdym żądaniu; zawsze aktualna, ale wymaga serwera Node i cache.
3. ISR / regeneracja na żądanie – strony statyczne odświeżane w tle po upływie czasu lub po sygnale z CMS.

Przy SSG i ISR WordPress musi powiadamiać frontend o zmianach. Najprościej zrobić to webhookiem przy publikacji:

add_action( 'transition_post_status', function ( $new_status, $old_status, $post ) {
    if ( 'publish' === $new_status || 'publish' === $old_status ) {
        wp_remote_post( 'https://api.example-hosting.com/build-hook/ABC123', [ 'blocking' => false ] );
    }
}, 10, 3 );

Co trzeba rozwiązać samodzielnie

To część, o której rzadko mówią entuzjastyczne prezentacje. W trybie headless sam odpowiadasz za:

• Podgląd szkiców. Przycisk „Podgląd” w WordPressie otwiera motyw, którego nie ma. Trzeba zbudować trasę podglądu we frontendzie, która z uwierzytelnieniem pobiera wersję roboczą.
• SEO. Tytuły, meta opisy, kanoniczne adresy, mapa witryny, przekierowania i dane strukturalne muszą być generowane przez frontend. Yoast SEO udostępnia dane meta w odpowiedziach REST API (pole yoast_head_json), a Rank Math ma opcję obsługi trybu headless – ale wyrenderować je musi Twoja aplikacja.
• Formularze, wyszukiwarka, komentarze. Wtyczki typu Contact Form 7 czy wyszukiwanie WordPressa nie wyświetlą się same; potrzebujesz integracji przez ich API albo zewnętrznych usług.
• Obrazki. Rozmiary generowane przez WordPress są dostępne w API, ale optymalizację, srcset i lazy loading konfiguruje frontend.
• Menu i ustawienia globalne. Menu są dostępne przez REST API (/wp-json/wp/v2/menu-items, wymaga uwierzytelnienia) lub WPGraphQL; opcje globalne często trzyma się w stronie opcji ACF.
• Kreatory stron. Elementor, Divi i podobne generują HTML oraz CSS dla motywu – w headless praktycznie się nie sprawdzają.

Ważne: Przed decyzją zrób listę wtyczek, z których korzysta obecna strona, i przy każdej sprawdź, czy działa w trybie headless. Jedna kluczowa wtyczka bez API potrafi znacząco zmienić zakres i koszt projektu.

Bezpieczeństwo i hosting w modelu headless

Oddzielenie frontendu od CMS poprawia bezpieczeństwo: odwiedzający nie mają kontaktu z PHP, a panel WordPressa może stać pod osobnym adresem, np. cms.firma.pl, dostępny tylko z VPN lub określonych adresów IP. Statyczny frontend nie ma bazy danych, którą można zaatakować.

Mimo to zadbaj o:

• ograniczenie publicznych endpointów, które nie są frontendowi potrzebne – np. /wp-json/wp/v2/users ujawnia loginy autorów,
• aktualizacje WordPressa i wtyczek – zaplecze nadal jest aplikacją PHP,
• uwierzytelnianie zapytań o szkice i treści prywatne (hasła aplikacji, JWT, klucze tylko po stronie serwera frontendu),
• CORS – jeśli przeglądarka odpytuje API bezpośrednio, zezwól tylko na domenę frontendu.

Samo ukrycie adresu panelu to za mało, o czym piszemy w tekście czy Hide WP Admin zabezpieczy WordPressa.

Hostingowo potrzebujesz dwóch rzeczy: zwykłego hostingu PHP/MySQL dla WordPressa (może być niewielki, bo obsługuje tylko redaktorów i zapytania przy budowaniu) oraz miejsca na frontend – hostingu statycznego, platformy obsługującej Node.js albo CDN.

Kiedy headless WordPress ma sens, a kiedy nie

Headless warto rozważyć, gdy:

• te same treści trafiają na stronę, do aplikacji mobilnej i innych kanałów,
• frontend ma być aplikacją z dużą interaktywnością, a zespół zna React, Vue lub Svelte,
• zależy Ci na maksymalnej wydajności i bezpieczeństwie serwisu treściowego o dużym ruchu,
• redaktorzy znają WordPressa i nie chcesz ich przenosić do innego CMS.

Lepiej zostać przy klasycznym WordPressie, gdy:

• to strona firmowa, blog lub sklep budowany w modelu „zainstaluj motyw i wtyczki”,
• nie masz programistów do utrzymania frontendu – każda zmiana wyglądu będzie wymagać pracy dewelopera,
• budżet jest ograniczony, a do szybkości wystarczy dobry hosting, cache i CDN.

Warto też porównać headless WordPressa z CMS-ami projektowanymi od początku jako headless (np. Strapi, Sanity, Payload, Directus) oraz z narzędziami no-code – o tym, jak WordPress wypada na tle Webflow, przeczytasz w porównaniu Webflow vs WordPress.