You migrate a WordPress site to a headless CMS by auditing content, remodeling it as structured types, exporting it from WordPress, and importing it before rebuilding the frontend. A headless CMS stores content and serves it through an API while a separate frontend renders pages, so themes and plugins must become code. The process fits teams with many post types, heavy page-builder layouts, or plans for Next.js, Astro, or Vue frontends. It also changes publishing work, URL handling, and maintenance duties.
Official resource:
- Explore the official data from Github — Use this primary source to review the underlying data.
Table of Contents
- What should you keep or drop?
- How do you reshape content for headless?
- How do you move posts and media?
- What needs rebuilding as code?
- How do you preserve search traffic?
What should you keep or drop?
Start with a full audit of posts, pages, custom post types, plugins, media, URLs, and integrations. Strapi recommends this inventory to decide what to keep, drop, or rebuild.
Drop unused drafts, duplicate media, dead plugins, and one-off landing pages. Keep revenue content, ranking pages, active integrations, and reusable media with clear rights.
How do you reshape content for headless?
Remodel WordPress content as structured content types and fields in the new CMS. Afteractive explains this step often means simplifying page-builder layouts into reusable components.
For example, turn a flexible sales page into a page type with headline, body, image, testimonial, and call-to-action fields. Turn repeated banners, cards, FAQs, and author bios into components editors can reuse.
How do you move posts and media?
WordPress exposes posts, pages, media, categories, and other resources as JSON through REST routes such as /wp/v2/posts, /wp/v2/pages, and /wp/v2/media, according to the WordPress REST API reference. Migration scripts can query those routes, download files and metadata, and write them to the new system.
Storyblok offers an official WordPress Importer script for this move, with CSV export recommended for reviewing and cleaning data first. Sanity Learn describes bulk-writing documents with the CLI command npx sanity@latest migration create in the Sanity migration course.
- Export content, media, categories, tags, authors, and URL slugs.
- Review and clean the export in CSV form before import.
- Map old fields to new content types, components, and media fields.
- Import in small batches and check counts, links, images, and formatting.
What needs rebuilding as code?
Rebuild the theme layer as a separate frontend that reads the CMS API. Strapi describes this split as API-served content plus a separately built frontend such as Next.js, Astro, or Vue.
Rebuild forms, search, comments, menus, previews, redirects, feeds, and plugin behavior in code or services. Assign owners for hosting, updates, backups, monitoring, and content previews.
How do you preserve search traffic?
Inventory every old URL before launch and keep URLs unchanged where possible. Search Engine Watch advises single-hop permanent 301 redirects for changed URLs plus rebuilt metadata, sitemaps, and robots rules in its headless migration guide.
Watch for hidden WordPress post types and custom fields that stay out of the REST API unless explicitly enabled. A migration can finish without errors yet miss that content, so compare source counts against imported items field by field.




