Czym jest headless CMS? Jak działa, kiedy go wybrać i przykład ze Strapi

Headless CMS to jedno z haseł, które najczęściej pojawia się obok Next.js i Reacta. Poniżej wyjaśniamy, czym jest i jak działa, pokazujemy działający przykład w Strapi, opisujemy najczęstsze problemy i podpowiadamy, kiedy się opłaca. Jeśli dopiero poznajesz systemy zarządzania treścią, zacznij od artykułu Czym jest CMS.

Czym jest headless CMS?

Headless CMS to system zarządzania treścią bez „głowy”, czyli bez gotowej warstwy, która zamienia treść na stronę widoczną w przeglądarce. Dostajesz panel dla redaktorów, bazę i API. Wygląd strony budujesz samodzielnie, w dowolnej technologii. To podejście bywa nazywane API-first.

W tradycyjnym CMS-ie, takim jak WordPress, panel, baza i wyświetlanie to jedna aplikacja. W headless CMS są to dwie osobne części, które łączy API:

Czym headless CMS różni się od tradycyjnego?

Zalety i wady wynikają z tej różnicy. Zyskujesz swobodę technologiczną, jedno źródło treści i możliwość zbudowania szybkiego frontendu. Płacisz dłuższym startem, koniecznością zbudowania wszystkiego samodzielnie (podglądu, wyszukiwarki, formularzy) i tym, że do każdej zmiany układu potrzebny jest programista.

Jak wygląda headless CMS w praktyce? Przykład ze Strapi

Najłatwiej zrozumieć to na działającym przykładzie. Użyjemy Strapi, otwartoźródłowego headless CMS-a napisanego w JavaScripcie. Przykład uruchomiliśmy w wersji 5.61.0 na Node 22 z bazą SQLite. Strapi wspiera obecnie Node 22, 24 i 26 (wersje nieparzyste nie są wspierane).

Jak utworzyć projekt?

npx create-strapi@latest blog-cms --non-interactive --skip-cloud --use-npm
cd blog-cms
npm run develop

Pierwsze polecenie tworzy projekt z domyślną bazą SQLite, bez logowania do chmury Strapi i bez przykładowych danych. Po instalacji npm run develop uruchamia serwer pod adresem http://localhost:1337, a panel administracyjny jest dostępny pod /admin. Przy pierwszym wejściu tworzysz konto administratora.

Jak dodać typ treści?

W panelu wchodzisz w Content-Type Builder i tworzysz typ „Article” z polami title (tekst), slug (identyfikator URL), body (tekst) oraz relacją do typu „Author”. To właśnie jest model treści, czyli opis tego, jakie dane przechowujesz. Strapi na tej podstawie sam wystawia adres /api/articles.

Dlaczego dostaję błąd 403, zanim pobiorę jakiekolwiek dane?

To najczęstszy problem początkujących. Pierwsze zapytanie do świeżego projektu:

const res = await fetch("http://localhost:1337/api/articles");
console.log(res.status);

zwraca 403 Forbidden. Nie znaczy to, że serwer się zepsuł. Wszystkie typy treści są domyślnie prywatne. Masz dwie możliwości: nadać rolę Public uprawnienie find w Settings → Users & Permissions → Roles → Public albo wysłać zapytanie z tokenem w nagłówku Authorization: Bearer <token>. Po nadaniu uprawnienia to samo zapytanie zwraca 200 i listę opublikowanych wpisów.

Jak pobrać artykuły razem z autorem?

Funkcja, którą uruchomiliśmy w Node 22:

async function getArticles() {
  const res = await fetch("http://localhost:1337/api/articles?populate=author");
  if (!res.ok) throw new Error(`CMS HTTP ${res.status}`);
  const { data, meta } = await res.json();
  return {
    articles: data.map((a) => ({ title: a.title, author: a.author?.name ?? "brak autora" })),
    total: meta.pagination.total,
  };
}

console.log(await getArticles());

Wynik dla przykładowych danych to { articles: [{ title: 'Pierwszy wpis', author: 'Ola Nowak' }], total: 1 }. Odpowiedź ma trzy części: data z dokumentami, meta z paginacją (domyślnie 25 wpisów na stronę) i error tylko przy błędzie. Pola leżą na najwyższym poziomie dokumentu, a pojedynczy dokument pobierasz po jego documentId.

Przydatne parametry zapytania sprawdziliśmy w praktyce:

Jakie są najczęstsze problemy z headless CMS?

Pytania ze Stack Overflow pokazują, że w większości przypadków przyczyną jest konfiguracja, nie błąd w kodzie. W naszych testach powtórzyły się trzy objawy:

Dwie uwagi praktyczne. Po pierwsze, sprawdź, czy pole slug jest wypełnione: w naszym teście wpisy utworzone przez API miały slug: null, więc filtr po slugu nic nie zwrócił, a w panelu administracyjnym slug wypełnia się z tytułu. Po drugie, na forach często pojawiają się też pytania o wdrożenie Strapi na Vercel i o błąd modułu sharp na Windowsie. Tych przypadków nie testowaliśmy, więc sprawdź dokumentację przed wdrożeniem.

Jakie headless CMS-y są dziś najpopularniejsze?

Liczby z GitHuba pochodzą z 8 listopada 2026 i rosną z dnia na dzień, a ceny planów chmurowych pomijamy, bo często się zmieniają. Przetestowaliśmy tylko Strapi, więc opisy pozostałych opierają się na ich dokumentacji. Pełniejsze porównanie z systemami tradycyjnymi znajdziesz w artykule o CMS-ach.

Kiedy warto wybrać headless CMS?

Nasza prosta reguła: headless wybierz wtedy, gdy frontend i tak piszą programiści, a nie dlatego, że jest modny. Jeśli redaktor chce tylko zmienić tekst na stronie wizytówki, WordPress lub kreator będzie tańszy i szybszy do uruchomienia, a headless dołoży Ci pracy bez widocznej korzyści. Zaczyna się opłacać, gdy masz programistę i zależy Ci na swobodzie. W sklepach działa to podobnie: Shopify oferuje podejście headless w ramach frameworka Hydrogen, o czym piszemy w artykule o zawodzie Shopify developera.

Czy headless CMS wymaga znajomości Next.js i Reacta?

Nie musi, bo API jest niezależne od technologii, a pobierać dane możesz z dowolnego języka. W praktyce headless CMS najczęściej łączy się z Next.js i Reactem, bo dobrze radzą sobie z tworzeniem stron wcześniej, co jest ważne dla szybkości i indeksacji w wyszukiwarkach. Jeśli chcesz pójść tą drogą, zacznij od czym jest React, potem przejdź do Next.js, a podstawy HTML, CSS i JavaScript możesz utrwalić w naszym kursie frontendu.