Headless WordPress z Next.js — kiedy ma sens, a kiedy nie

W tym artykule pokażę, kiedy headless WordPress + Next.js to bardzo dobry wybór, a kiedy lepszym rozwiązaniem jest tradycyjny WordPress.

Jeśli decyzja jest już podjęta i potrzebujesz technicznej implementacji, przejdź do tutoriala WPGraphQL + Next.js App Router — implementacja headless WordPress krok po kroku.

Czym jest headless WordPress?

Tradycyjny WordPress to monolit:

Użytkownik → WordPress → Baza danych
                ↓
              Szablony PHP → HTML

Headless WordPress oddziela backend od frontendu:

Użytkownik → Next.js (frontend)
                ↓
            REST API / GraphQL
                ↓
            WordPress (backend) → Baza danych

WordPress zarządza treścią i wystawia ją przez REST APIREST API to interfejs udostępniający dane przez standardowe metody HTTP (GET, POST...) pod adresami zasobów — w WordPressie domyślnie pod /wp-json/. lub GraphQLGraphQL to język zapytań do API, w którym klient precyzyjnie określa, jakie pola chce pobrać — zamiast sztywnych endpointów REST zwracających całe obiekty., a Next.js renderuje interfejs.

Zalety headless

1. Wydajność

Next.js oferuje strategie, które WordPress nie obsługuje natywnie:

// Static Site Generation — HTML generowany przy buildzie
export async function generateStaticParams() {
  const posts = await getPosts()
  return posts.map((post) => ({ slug: post.slug }))
}
 
// Incremental Static Regeneration — rewalidacja w tle
export const revalidate = 60 // Odśwież co 60 sekund
 
// Server Components — streaming, partial hydration
export default async function Page() {
  const posts = await getPosts() // Wykonuje się na serwerze
  return <PostList posts={posts} />
}

Wynik? Strony ładują się w milisekundach, a Core Web Vitals się poprawiają.

2. Lepsza praca programistyczna

// TypeScript, komponenty, hooks
interface Post {
  id: number
  title: string
  slug: string
  content: string
}
 
function PostCard({ post }: { post: Post }) {
  return (
    <article className="p-4 border rounded-lg">
      <h2 className="text-xl font-bold">{post.title}</h2>
    </article>
  )
}

Zamiast szablonów PHP masz React — lepsze narzędzia, automatyczne odświeżanie po zmianach i kontrolę typów.

3. Elastyczność frontendu

Motyw WordPressa ogranicza Cię do tego, co zostało przewidziane przez autora, ale w React możesz zbudować znacznie bardziej dopasowany do swoich potrzeb interfejs:

• Interaktywne panele
• Animacje i przejścia
• Aktualizacje w czasie rzeczywistym
• Progressive Web App
• Współdzielony kod z aplikacją mobilną (React Native)

4. Bezpieczeństwo

Frontend nie ma bezpośredniego dostępu do bazy danych:

Atak na frontend → Next.js (statyczny HTML)
                      ↓
                  API (tylko odczyt)
                      ↓
                  WordPress (ukryty, może być w VPN)

Panel administracyjny WordPressa może być schowany przed światem, co zmniejsza powierzchnię ataku.

5. Skalowalność

           ┌──────────────────────┐
           │   CDN (Vercel/CF)    │ ← miliony żądań, cache edge
           └──────────┬───────────┘
                      │
           ┌──────────▼───────────┐
           │     Next.js          │ ← serverless, autoskalowanie
           └──────────┬───────────┘
                      │
           ┌──────────▼───────────┐
           │   WordPress API      │ ← jeden serwer, rzadkie żądania
           └──────────────────────┘

Frontend skaluje się automatycznie, podczas gdy backend obsługuje głównie redaktorów i żądania APIAPI, czyli Application Programming Interface, definiuje sposób komunikacji między aplikacjami lub modułami. Tu chodzi o konwencje plików Next.js, które zamieniają eksportowaną funkcję w gotowy plik sitemap.xml lub robots.txt. związane z ISRISR, czyli Incremental Static Regeneration, pozwala odświeżać strony statyczne w tle bez pełnego rebuildu — strona jest serwowana z cache, a Next.js regeneruje ją po upływie czasu revalidate..

Wady headless

1. Złożoność

Zamiast jednego systemu masz równolegle dwa:

2. Podgląd i edycja

W tradycyjnym WP klikasz "Podgląd" i widzisz dokładnie, jak wygląda wpis - w headless trzeba zbudować ten mechanizm osobno:

// Musisz zbudować osobny system podglądu
// app/api/draft/route.ts
import { draftMode } from 'next/headers'
import { redirect } from 'next/navigation'
 
export async function GET(request: Request) {
  const { searchParams } = new URL(request.url)
  const postId = searchParams.get('post_id')
  const secret = searchParams.get('secret')
 
  if (secret !== process.env.PREVIEW_SECRET) {
    return new Response('Invalid secret', { status: 401 })
  }
 
  // Włącz Draft Mode (Next.js 13.4+)
  const draft = await draftMode()
  draft.enable()
 
  redirect(`/blog/preview/${postId}`)
}

Każda interakcja między treścią a frontendem wymaga kodu.

3. Wtyczki przestają działać

Wtyczka "Contact Form 7"? Nie renderuje się na Next.js, dlatego trzeba zrobić tak:

• Przebudować formularz w React,
• Stworzyć endpoint API,
• Obsłużyć walidację i wysyłkę.

// To co w WP zajmuje 5 minut, tutaj to kilka godzin
async function handleSubmit(data: FormData) {
  const response = await fetch('/api/contact', {
    method: 'POST',
    body: JSON.stringify({
      name: data.get('name'),
      email: data.get('email'),
      message: data.get('message'),
    }),
  })
 
  if (!response.ok) {
    throw new Error('Failed to send')
  }
}

4. SEO wymaga uwagi

WordPress z Yoastem daje dużą część SEOSEO, czyli Search Engine Optimization, to optymalizacja strony pod widoczność w wynikach wyszukiwania. od razu po konfiguracji. W Next.js musisz tę warstwę zbudować świadomie:

// app/blog/[slug]/page.tsx
export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const post = await getPost(slug)
  const yoastData = post.yoast_head_json // jeśli masz Yoast API
 
  return {
    title: yoastData?.title || post.title,
    description: yoastData?.description || post.excerpt,
    openGraph: {
      title: yoastData?.og_title,
      description: yoastData?.og_description,
      images: [yoastData?.og_image?.[0]?.url],
    },
  }
}

5. WooCommerce mocno podnosi koszt headless

E-commerce w headless jest możliwy, ale zwykle przestaje być "prostym WordPressem z Reactem", ponieważ dochodzi bardzo dużo logiki, którą w klasycznym WooCommerce dostajesz praktycznie od razu. I tak:

• Koszyk i proces zakupowy — musisz zbudować od zera,
• Płatności — integracja z Przelewy24/Stripe po Twojej stronie,
• Stan magazynowy — synchronizacja w czasie rzeczywistym,
• Kupony, rabaty i wysyłka — logika jest do przepisania.

Dla większości sklepów lepszym wyborem będzie klasyczny WooCommerce.

Najczęściej pomijanym kosztem jest proces redakcyjny

Na slajdzie sprzedażowym headless wygląda bardzo prosto: WordPress do treści, Next.js do frontendu. W praktyce największy koszt często nie leży w samym renderowaniu, ale w codziennej pracy zespołu redakcyjnego.

Musisz przemyśleć:

• Podgląd szkiców: redaktor oczekuje przycisku "Podgląd", który naprawdę pokazuje szkic na froncie.
• Webhooki i rewalidację: po publikacji wpisu frontend musi się odświeżyć bez ręcznego wdrożenia.
• Unieważnianie cache: jeśli cache jest agresywny, redakcja widzi stare treści i zgłasza błędy, których technicznie już nie ma.
• Obsługę bloków i shortcodów: REST API zwraca post.content.rendered jako surowy HTML — renderowanie go przez dangerouslySetInnerHTML otwiera XSS, a parseowanie bloków do komponentów React to nietrywialny zakres. WPGraphQL radzi sobie z tym lepiej przez dedykowaną schemę bloków Gutenberga, ale wtedy musisz zrezygnować z prostoty REST.
• Wyszukiwarkę, okruszki nawigacyjne, powiązane wpisy i formularze: w tradycyjnym WP to często jedna wtyczka, a w headless to osobny zakres implementacji.

Drzewo decyzyjne

Czy potrzebujesz WooCommerce?
├─ TAK → Tradycyjny WordPress
└─ NIE → Czy zespół redakcyjny zna tylko WordPressa?
         ├─ TAK → Czy budżet > 50k na dopracowaną edycję treści?
         │        ├─ TAK → Headless możliwy
         │        └─ NIE → Tradycyjny WordPress
         └─ NIE → Czy potrzebujesz niestandardowych interakcji (animacje, panele)?
                  ├─ TAK → Headless WordPress
                  └─ NIE → Czy Core Web Vitals są krytyczne?
                           ├─ TAK → Headless lub WP + wtyczka cache
                           └─ NIE → Tradycyjny WordPress

Realne przypadki użycia

✅ Headless ma sens

Blog firmowy z niestandardowym projektem graficznym

• Treści zarządzane przez marketing w WP,
• Projekt wdrażany przez zespół frontendowy w React,
• Wydajność krytyczna dla SEO,
• Brak e-commerce.

Portal informacyjny

• Tysiące artykułów,
• Wielu edytorów,
• Potrzeba testów A/B układu strony,
• Wysokie wymagania wydajnościowe.

Strona produktowa SaaS

• Strona główna + blog w WordPress,
• Aplikacja w React,
• Wspólny design system,
• Potrzeba szybkich zmian treści bez wdrożenia.

❌ Tradycyjny WP lepszy

Sklep internetowy

• WooCommerce robi większość pracy,
• Wtyczki do płatności, wysyłki i faktur,
• Headless = miesiące dodatkowej pracy,

Mała strona firmowa

• 5-10 podstron
• Formularz kontaktowy
• Edycja przez właściciela
• Budżet < 10k

Strona z wieloma wtyczkami

• System rezerwacji,
• Strefy członkowskie,
• LMS (kursy online),
• Każda wtyczka = osobny kod w React.

Alternatywy do rozważenia

Zanim zdecydujesz się na headless WordPress, przemyśl dobrze alternatywne rozwiązania:

1. WordPress + dobry hosting + cache

WordPress + LiteSpeed Cache + CDN
= znaczna poprawa TTFB i Core Web Vitals
= ułamek kosztów wdrożenia headless

2. Statyczny generator + headless CMS

Sanity / Strapi / Contentful + Next.js
= Wygodniejsza edycja treści niż przez WP API
= Brak bagażu PHP
= Wyższe koszty CMS (dla dużych projektów)

3. Next.js + MDX (dla blogów technicznych)

Markdown w repozytorium
= Bez CMS-a
= Praca z treścią przez Git
= Najlepsza wydajność

Jak zacząć (jeśli zdecydujesz się na headless)

1. Proof of ConceptProof of Concept (PoC) to krótki eksperyment techniczny, który sprawdza, czy wybrane rozwiązanie działa w praktyce, zanim zespół zainwestuje w pełne wdrożenie.

Zanim przepiszesz cały serwis:

npx create-next-app@latest headless-poc
cd headless-poc

// app/page.tsx
async function getPosts() {
  const res = await fetch(
    'https://twoj-wordpress.pl/wp-json/wp/v2/posts?_embed=true'
  )
  return res.json()
}
 
export default async function Home() {
  const posts = await getPosts()
 
  return (
    <main>
      <h1>PoC - Headless WordPress</h1>
      {posts.map((post) => (
        <article key={post.id}>
          {/* .rendered zawiera encje HTML — dekoduj przez bibliotekę (np. he),
              nie przez dangerouslySetInnerHTML, które otwiera XSS */}
          <h2>{decodeHtmlEntities(post.title.rendered)}</h2>
        </article>
      ))}
    </main>
  )
}

Oceń po 2-3 dniach, czy to ma sens.

2. Infrastruktura

WordPress:
├─ Hosting: dowolny z PHP 8+ i SSL
├─ Wtyczki: ACF (pola niestandardowe), Yoast (SEO API), JWT Auth (tylko przy draft mode lub endpointach wymagających uwierzytelnienia)
└─ Cel: Tylko admin, ukryty za VPN (opcjonalnie)

Next.js:
├─ Hosting: Vercel (najprostszy) lub Netlify
├─ CI/CD: GitHub Actions → automatyczne wdrożenie
└─ Cel: Publiczny frontend

3. Plan migracji

Tydzień 1: Konfiguracja infrastruktury, PoC
Tydzień 2-3: Kluczowe strony (home, about, contact)
Tydzień 4-5: Lista wpisów + pojedynczy wpis
Tydzień 6: SEO, metadane, sitemap
Tydzień 7: Tryb podglądu, przypadki brzegowe
Tydzień 8: Testy, kontrola jakości, publikacja

To plan dla doświadczonego zespołu pracującego wyłącznie nad tym projektem i ograniczonego zakresu. Jeśli dochodzą wielojęzyczność, wyszukiwarka, zaawansowane SEO, niestandardowe bloki i rozbudowany proces redakcyjny, harmonogram bardzo szybko się wydłuża.

Headless czy tradycyjny WP — tabela decyzyjna