Migracja z WordPressa do Astro lub Next.js i Headless CMS

Migracja z WordPressa do Headless CMS: czy redakcja traci panel?

Headless nie oznacza Markdowna w Gicie, ponieważ nowoczesny frontend w Astro albo Next.js może współpracować z wizualnym panelem do zarządzania treścią, a redaktor nadal edytuje wpisy, strony i media w aplikacji CMS.

W praktyce zmienia się odpowiedzialność systemu: frontend odpowiada za szybkość i prezentację, a Headless CMS za treść, role użytkowników, media i workflow redakcyjny. Dzięki temu zespół techniczny odzyskuje kontrolę nad kodem, a redakcja nie musi pracować w przeładowanym panelu WordPressa.

Dlaczego WordPress z page builderem utrudnia migrację

Treść i layout w jednej bazie WordPressa

To najgłębszy problem architektury WordPressa z page builderem. W bazie danych treść (tekst) jest wymieszana z prezentacją (style, układ, shortcode'y Elementora czy Divi). Jeden wpis w bazie to nie „tytuł i akapity", tylko tytuł, akapity, definicje kolumn, kolory tła, marginesy i shortcode'y buildera zapisane razem w jednym polu.

Wszystko ma swoje konsekwencje i gdy chcesz zmienić szablon albo zmigrować dane, baza okazuje się chaosem, z którego trzeba wydłubywać czystą treść. Mozolny i nieprzyjemny proces. Headless CMS wymusza rozdzielenie tych warstw, czyli treść to treść, a jej wygląd definiuje frontend. Dzięki takiemu podejściu, gdy na przyład, za trzy lata będziesz zmieniać cały layout, zrobisz to bez dotykania ani jednego wpisu.

Wolny panel WordPressa i gorszy UX edytora

Jako wieloletni posiadacz stron w WordPressie mogę powiedzieć z doświadczenia: panel administratora z czasem zwalnia. Jest to bardzo frustrujące, ponieważ z czasem chcemy pracować szybciej. WordPress ma to do siebie, że im więcej wtyczek, tym dłużej się ładuje, mamy więcej komunikatów o aktualizacjach i blokad przy edycji.

Nowoczesne panele (Sanity Studio, panel Payloada, edytor Storybloka) są budowane jak aplikacje frontendowe, więc ładują się natychmiast i skupiają tylko na edycji treści.

Bezpieczeństwo WordPressa: panel, wtyczki i dostęp do serwera

W monolitycznym WordPressie dając redaktorowi dostęp do panelu, dajesz mu także możliwość zainstalowania losowej wtyczki, która zepsuje albo skompromituje stronę. W architekturze headless panel CMS i frontend to dwa oddzielne światy. Redaktor pracuje w panelu treści, który fizycznie nie ma jak zmodyfikować kodu strony ani serwera, na którym stoi frontend.

Jaki Headless CMS po WordPressie: Storyblok, Sanity czy Payload?

Wybierając najlepszy CMS, trzeba kierować się przede wszystkim dobrze przemyślanymi, własnymi potrzebami. Są trzy sprawdzone kierunki:

Storyblok: wizualna edycja treści po migracji z WordPressa

Storyblok ma wbudowaną edycję wizualną z podglądem na żywo (Visual Editor): redaktor widzi realną stronę, klika w element i edytuje go w bocznym pasku. To najbliższy odpowiednik doświadczenia z Elementora. Jeśli klient panicznie boi się, że „straci klikanie", Storyblok będzie dla niego.

Sanity: elastyczne modelowanie treści w Headless CMS

Sanity daje pełną swobodę w projektowaniu schematów treści (Content Modeling), dlatego zamiast dopasowywać się do sztywnych typów pól, definiujesz dokładnie taką strukturę, jakiej potrzebuje Twój projekt. Masz wpływ na pola tekstowe, relacje między dokumentami czy powtarzalne bloki. Ostatecznie, redaktor dostaje czysty, intuicyjny panel (Sanity Studio) i bibliotekę mediów z automatyczną optymalizacją i punktem centrowania kadru (focal point). To dobry wybór, gdy zależy Ci na porządku w danych i długoterminowej elastyczności.

Payload CMS: samodzielne hostowanie i integracja z Next.js

Payload to CMS, który zakłada samodzielne hostowanie (stoi na Twoim serwerze, jak WordPress), z potężnym panelem opartym na React. Od wersji 3 jest natywny dla Next.js, co oznacza, że instaluje się bezpośrednio w folderze /app Twojej aplikacji. W rezultacie, CMS i frontend żyją w jednym repozytorium. Konfiguracja jest w TypeScripcie, dane są w pełni Twoje (licencja MIT), a integracja z Next.js jest najgłębsza na rynku. Jako ciekawostkę dodam, że po przejęciu Payloada przez Figmę (2025) hostowany Payload Cloud wstrzymał rejestracje. Oznacza to, że w praktyce hostujesz sam, np. na Vercelu, w kontenerze na VPS -ie albo na Cloudflare Workers. Dla zespołów bardziej inżynierskich, już siedzących w Next.js, to często najnaturalniejszy i najbardziej rozsądny wybór.

Architektura Headless CMS z Astro i Next.js po migracji

Warto to również przedstawić stronie biznesowej, ponieważ jest to argument, który przekonuje decydentów.

Dawniej (monolit): W tradycyjnym modelu monolitycznym, baza danych WordPressa, wraz z PHP i wtyczkami, generowała HTML, który następnie zostawał przesyłany do przeglądarki. Oznaczało to, że wszystkie elementy znajdowały się w jednym miejscu. Tworzyło to pojedynczy punkt awarii, a wydajność była bezpośrednio zależna od obciążenia serwera przy każdym żądaniu.

Teraz (architektura decoupled): W architekturze rozdzielonej, panel CMS (taki jak Sanity, Payload czy Storyblok) komunikuje się poprzez API z generatorem stron (Astro lub Next.js). W rezultacie powstaje gotowy, statyczny plik, który jest serwowany z CDN. Treść jest pobierana jednorazowo, na etapie budowania strony (lub na żądanie), a użytkownik otrzymuje błyskawiczny HTML bezpośrednio z sieci brzegowej.

Najważniejszą korzyścią biznesową jest niezależność. Jeśli za np. trzy lata zechcesz zmienić Astro na coś innego, treść w CMS-ie zostaje nienaruszona, a przepisujesz tylko warstwę prezentacji. W monolicie WordPressa taka zmiana oznaczała przepisanie wszystkiego naraz.

Migracja z WordPressa do Headless CMS krok po kroku

Krok 1: eksport i czyszczenie treści z WordPressa

Treść wyciągasz z WordPressa przez REST API (/wp-json/wp/v2/posts) albo WPGraphQL, a następnie usuwasz z niej „śmieci" po page builderach — shortcode'y, puste wrappery, inline'owe style. To ten sam etap, który opisałem szerzej w artykule o migracji frontendu; tutaj efektem ma być czysta treść gotowa do włożenia w schemat CMS-a.

Krok 2: Content Modeling i schematy w nowym CMS-ie

Na tym etapie należy zdefiniować schematy w nowym systemie CMS, odwzorowując dotychczasowe typy treści z WordPressa, takie jak wpisy blogowe, realizacje czy profile pracowników. Jest to najważniejszy moment, aby trwale uporządkować strukturę danych.

W Sanity schemat to obiekt w kodzie:

// schemas/post.ts
import { defineType, defineField } from 'sanity'
 
export const post = defineType({
  name: 'post',
  title: 'Wpis blogowy',
  type: 'document',
  fields: [
    defineField({ name: 'title', title: 'Tytuł', type: 'string' }),
    defineField({
      name: 'slug',
      title: 'Slug',
      type: 'slug',
      options: { source: 'title' },
    }),
    defineField({ name: 'coverImage', title: 'Zdjęcie', type: 'image' }),
    defineField({
      name: 'body',
      title: 'Treść',
      type: 'array',
      of: [{ type: 'block' }],
    }),
  ],
})

W Payloadzie ten sam typ to kolekcja:

// collections/Posts.ts
import type { CollectionConfig } from 'payload'
 
export const Posts: CollectionConfig = {
  slug: 'posts',
  admin: { useAsTitle: 'title' },
  fields: [
    { name: 'title', type: 'text', required: true },
    { name: 'slug', type: 'text', required: true, unique: true },
    { name: 'coverImage', type: 'upload', relationTo: 'media' },
    { name: 'content', type: 'richText' },
  ],
}

Krok 3: skrypt migracyjny do automatycznego importu

Ręczne przepisywanie setek wpisów jest pozbawione sensu, wiec tworzy się skrypt, który pobiera dane z WordPressa i przesyła je do API nowego systemu CMS za pośrednictwem jego SDK. Poniżej przykład dla Sanity, obejmujący pobranie wpisów, przesłanie zdjęcia głównego i zapis dokumentu:

// migrate.mjs
import { createClient } from '@sanity/client'
import 'dotenv/config'
 
const WP = 'https://stara-strona.pl/wp-json/wp/v2'
 
const sanity = createClient({
  projectId: process.env.SANITY_PROJECT_ID,
  dataset: 'production',
  apiVersion: '2026-01-01',
  token: process.env.SANITY_WRITE_TOKEN, // token z uprawnieniami do zapisu
  useCdn: false,
})
 
async function uploadImage(url) {
  if (!url) return undefined
  const res = await fetch(url)
  const buffer = Buffer.from(await res.arrayBuffer())
  const asset = await sanity.assets.upload('image', buffer)
  return { _type: 'image', asset: { _type: 'reference', _ref: asset._id } }
}
 
async function migrate() {
  const res = await fetch(`${WP}/posts?per_page=100&_embed`)
  const posts = await res.json()
 
  for (const post of posts) {
    const coverUrl = post._embedded?.['wp:featuredmedia']?.[0]?.source_url
    const doc = {
      _id: `post-${post.id}`, // stały identyfikator = idempotentny import
      _type: 'post',
      title: post.title.rendered,
      slug: { _type: 'slug', current: post.slug },
      coverImage: await uploadImage(coverUrl),
      // body: tu wstawiasz treść skonwertowaną do Portable Text
    }
    await sanity.createOrReplace(doc) // można puścić ponownie bez duplikatów
    console.log(`Zmigrowano: ${post.slug}`)
  }
}
 
migrate().catch(console.error)

Użycie stałego _id (post-${post.id}) i createOrReplace sprawia, że skrypt jest idempotentny. Oznacza to, że możesz puścić go wielokrotnie w trakcie dopracowywania mapowania i nie narobisz duplikatów. Paginację (per_page, page) dopisuj, gdy wpisów jest więcej niż setka.

Krok 4: webhooki, ISR i rebuild w Astro lub Next.js

Zastanawiasz się, skąd frontend wie, że pojawiła się nowa treść? Odpowiedzią są webhooki. Redaktor klika „Publikuj" w panelu, CMS wysyła żądanie do frontendu, a ten przebudowuje odpowiednie strony w kilka sekund.

W Next.js robisz to przez on-demand revalidation, czyli endpoint, który CMS wywołuje po publikacji:

// app/api/revalidate/route.ts
import { revalidateTag } from 'next/cache'
 
export async function POST(req: Request) {
  const secret = req.headers.get('x-webhook-secret')
  if (secret !== process.env.REVALIDATE_SECRET) {
    return Response.json({ ok: false }, { status: 401 })
  }
  revalidateTag('posts') // odświeża wszystko oznaczone tym tagiem
  return Response.json({ revalidated: true })
}

Jeśli Astro jest hostowane na Cloudflare Pages lub Netlify, zazwyczaj wystarczy skonfigurować webhook typu „deploy hook”. CMS, wysyłając żądanie na wskazany URL, automatycznie uruchamia szybką przebudowę statycznej strony. Dla treści, która musi być świeża natychmiast, Astro oferuje też renderowanie na żądanie (SSR) z pobieraniem danych w czasie requestu.

Lista kontrolna migracji z WordPressa do Astro, Next.js i Headless CMS

Przed startem migracji sprawdź nie tylko CMS i frontend, ale też import danych, media, webhooki oraz przekierowania. To one decydują, czy przejście z WordPressa na Astro lub Next.js będzie technicznie czyste i bezpieczne dla SEO.

• Zinwentaryzowane typy treści z WordPressa (wpisy, realizacje, strony, CPT).

• Wybrany CMS dopasowany do zespołu (Storyblok to wizualny komfort, Sanity oznacza elastyczność, Payload to samodzielne hostowanie i integracja z Next.js).

• Zaprojektowane schematy / kolekcje w nowym CMS-ie.

• Treść wyciągnięta z WP i oczyszczona z shortcode'ów page buildera.

• Idempotentny skrypt migracyjny przetestowany na próbce wpisów.

• Przeniesione i zoptymalizowane media.
• Skonfigurowane webhooki / rewalidacja po publikacji.

• Mapowanie starych URL-i i przekierowania 301 (żeby nie stracić SEO).

• Live Preview skonfigurowany i pokazany redakcji przed startem.