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

W tym artykule pokażę, kiedy headless WordPress + Next.js to strzał w dziesiątkę, a kiedy tradycyjny WordPress wygrywa bez dyskusji.

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 monolith:

Użytkownik → WordPress → Baza danych
                ↓
              PHP Templates → 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, Core Web Vitals rosną.

2. Nowoczesny developer experience

// 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 PHP templates masz React — lepszy tooling, hot reload, type safety.

3. Elastyczność frontendu

WordPress theme ogranicza Cię do tego, co autor przewidział. Z React możesz zbudować dosłownie wszystko:

• Interaktywne dashboardy
• Animacje i przejścia
• Real-time updates
• 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)

WordPress admin może być schowany przed światem — zmniejsza surface attack.

5. Skalowalność

           ┌──────────────────────┐
           │   CDN (Vercel/CF)    │ ← miliony requestów, cache edge
           └──────────┬───────────┘
                      │
           ┌──────────▼───────────┐
           │     Next.js          │ ← serverless, auto-scaling
           └──────────┬───────────┘
                      │
           ┌──────────▼───────────┐
           │   WordPress API      │ ← jeden serwer, rzadkie requesty
           └──────────────────────┘

Frontend skaluje się automatycznie. Backend obsługuje tylko edytorów i 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. calls 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 dwa:

2. Preview i editing

W tradycyjnym WP klikasz "Podgląd" i widzisz dokładnie jak post wygląda. W headless:

// Musisz zbudować osobny system preview
// app/api/preview/route.ts
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 })
  }
  
  // Ustaw cookie preview mode
  const response = NextResponse.redirect(`/preview/${postId}`)
  response.cookies.set('__preview', 'true')
  
  return response
}

Każda interakcja content/frontend wymaga kodu.

3. Pluginy przestają działać

Wtyczka "Contact Form 7"? Nie renderuje się na Next.js. Musisz:

• 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 + Yoast = SEOSEO, czyli Search Engine Optimization, to optymalizacja strony pod widoczność w wynikach wyszukiwania. out of the box. W Next.js musisz to zbudować:

// 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". Dochodzi dużo logiki, którą w klasycznym WooCommerce dostajesz prawie za darmo:

• Koszyk i checkout — musisz zbudować od zera
• Płatności — integracja z Przelewy24/Stripe po Twojej stronie
• Stan magazynowy — synchronizacja real-time
• Kupony, rabaty, shipping — logika do przepisania

Dla sklepu zostań przy tradycyjnym WooCommerce. Serio.

Najczęściej pomijany koszt: workflow redakcyjny

Na slajdzie sprzedażowym headless wygląda pięknie: WordPress do contentu, Next.js do frontendu. W praktyce największy koszt często nie siedzi w samym renderowaniu, tylko w codziennej pracy content teamu.

Musisz przemyśleć:

• Preview draftów: redaktor oczekuje przycisku "Podgląd", który naprawdę pokazuje szkic na froncie.
• Webhooks i rewalidację: po publikacji wpisu frontend musi się odświeżyć bez ręcznego deploya.
• Cache invalidation: 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: nie każdy element z klasycznego WordPressa ma sensowny odpowiednik po stronie Reacta.
• Wyszukiwarkę, breadcrumbs, related posts, formularze: w tradycyjnym WP to często jedna wtyczka. W headless to osobny zakres implementacji.

Decision tree

Czy potrzebujesz WooCommerce?
├─ TAK → Tradycyjny WordPress
└─ NIE → Czy content team zna tylko WordPress?
         ├─ TAK → Czy budżet > 50k na custom editing experience?
         │        ├─ TAK → Headless możliwy
         │        └─ NIE → Tradycyjny WordPress
         └─ NIE → Czy potrzebujesz custom interakcji (animacje, dashboard)?
                  ├─ TAK → Headless WordPress
                  └─ NIE → Czy Core Web Vitals są krytyczne?
                           ├─ TAK → Headless lub WP + cache plugin
                           └─ NIE → Tradycyjny WordPress

Realne przypadki użycia

✅ Headless ma sens

Blog firmowy z custom designem

• Content managowany przez marketing w WP
• Design implementowany przez frontend team w React
• Wydajność krytyczna dla SEO
• Brak e-commerce

Portal informacyjny

• Tysiące artykułów
• Wielu edytorów
• Potrzeba A/B testów layoutu
• Wysokie wymagania wydajnościowe

Strona produktowa SaaS

• Strona główna + blog w WordPress
• Aplikacja w React
• Wspólny design system
• Potrzeba szybkich zmian contentu bez deploya

❌ Tradycyjny WP lepszy

Sklep internetowy

• WooCommerce robi 90% roboty
• Pluginy do płatności, wysyłki, faktur
• Headless = miesiące developmentu

Mała strona firmowa

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

Strona z wieloma wtyczkami

• Booking system
• Member areas
• LMS (kursy online)
• Każda wtyczka = custom kod w React

Alternatywy do rozważenia

Zanim zdecydujesz się na headless WordPress, rozważ:

1. WordPress + dobry hosting + cache

WordPress + LiteSpeed Cache + CDN
= 90% wydajności headless
= 10% kosztów developmentu

2. Statyczny generator + headless CMS

Sanity / Strapi / Contentful + Next.js
= Lepszy editing experience niż WP API
= Brak bagażu PHP
= Wyższe koszty CMS (dla dużych projektów)

3. Next.js + MDX (dla dev-blogerów)

Markdown w repozytorium
= Zero CMS
= Git-based workflow
= Najlepsza wydajność

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

1. Proof of Concept

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}>
          <h2 dangerouslySetInnerHTML={{ __html: post.title.rendered }} />
        </article>
      ))}
    </main>
  )
}

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

2. Infrastruktura

WordPress:
├─ Hosting: dowolny z PHP 8+ i SSL
├─ Pluginy: ACF (custom fields), Yoast (SEO API), JWT Auth
└─ Cel: Tylko admin, ukryty za VPN (opcjonalnie)

Next.js:
├─ Hosting: Vercel (najprostszy) lub Netlify
├─ CI/CD: GitHub Actions → auto deploy
└─ Cel: Publiczny frontend

3. Plan migracji

Tydzień 1: Setup infrastruktury, PoC
Tydzień 2-3: Core pages (home, about, contact)
Tydzień 4-5: Blog listing + single post
Tydzień 6: SEO, metadata, sitemap
Tydzień 7: Preview mode, edge cases
Tydzień 8: Testing, QA, launch

To plan dla doświadczonego zespołu i ograniczonego zakresu. Jeśli dochodzą wielojęzyczność, search, zaawansowane SEO, niestandardowe bloki i rozbudowany workflow redakcyjny, harmonogram bardzo szybko się wydłuża.

Headless czy tradycyjny WP — tabela decyzyjna