WordPress to Contentful Migration: The Complete Guide
React
September 3, 2026•3 min read
I hope you enjoy reading this post. If you want us to do your frontend development or design, click here.
Author: Alex Vasylenko | Founder of The Frontend Company
Migrating WordPress to Contentful is a five-stage project: audit and map your content, design the Contentful content model, run an export-transform-import pipeline (the transform - WordPress HTML into Contentful Rich Text - is where the real work hides), rebuild or adapt the frontend, and cut over with redirects and SEO intact. For a typical marketing site or blog that's weeks, not days - and the projects that go wrong go wrong at the modeling and Rich Text stages, not at the export button.
One thing up front: we've built and run Contentful in production for years, built migration tooling around its Rich Text model, and done migrations both into and out of it. The pitfalls below are ones we've actually debugged, not paraphrased from docs.
When does moving from WordPress to Contentful make sense?
WordPress still powers about 41% of all websites, so “everyone is leaving WordPress” is marketing, not data. The move earns its cost in specific situations:
- Content goes multi-channel. The same content feeds a website, an app, and campaign surfaces - a headless API beats theme templates.
- The editorial team outgrows wp-admin. Contentful's roles, workflows, localization, and app marketplace are built for structured content operations at scale - the company reports nearly 30% of the Fortune 500 among its users.
- The frontend is going React or Next.js anyway. If a rebuild is happening, decoupling content is the natural moment.
- Plugin fatigue is real. When the plugin stack is the site's main risk register, structured content plus a modern frontend resets the maintenance story.
The honest counter-list: migration is usually the wrong move when a small team just blogs (WordPress is excellent at that), when the budget covers the CMS switch but not the frontend that has to be rebuilt with it, or when “WordPress is slow” is actually a hosting-and-theme problem fixable in a week. Contentful vs WordPress isn't better versus worse - it's a structured content platform versus a monolithic publishing tool. Match the tool to the team.
Step 1: the pre-migration audit
Before touching an API, inventory what exists:
- Content inventory. Every post type, page, custom post type, taxonomy, author, and media item - with counts. Surprises here become budget overruns later.
- URL map. Every live URL and its traffic value (a Search Console export). This becomes the redirect map and the definition of done.
- Field archaeology. Shortcodes, page-builder blocks (Elementor, WPBakery), ACF fields - each needs a decision: becomes structured data, becomes rich text, or dies here.
- Kill list. A migration is the cheapest moment to delete. Thin, outdated, or duplicate content shouldn't pay the transfer fare.
Step 2: content modeling in Contentful
The step everyone underestimates. WordPress stores a post as a blob of HTML; Contentful wants structured content types with typed fields and references. What good modeling looks like:
- Model by meaning, not by page: an article type with references to author and category entries beats one mega-type with forty fields.
- Decide what leaves the body: pull-quotes, CTAs, FAQ blocks, and galleries work better as referenced or embedded entries than as HTML fragments - that's what makes content reusable across channels.
- Treat assets as first-class entries with alt text and metadata, not as URLs inside HTML.
- Prototype with ten representative real posts - including your ugliest page-builder one - before migrating ten thousand.
Step 3: the export-transform-import pipeline
The mechanics are three moves:
- Export. The WordPress REST API (paginated JSON - our default) or a WXR export file. REST gives rendered HTML plus metadata; WXR gives everything, including drafts.
- Transform. The heart of the migration: convert WordPress HTML into Contentful's Rich Text format - a JSON tree of typed nodes (paragraphs, headings, lists, embedded entries and assets), not an HTML string. Every shortcode and builder block needs an explicit mapping rule, media URLs must be rewritten to uploaded Contentful assets, and internal links should resolve to entry references so they survive future URL changes.
- Import. The Contentful Management API, scripted - contentful-cli and the management SDK are the sane route - with batching and backoff for rate limits, run environment-first: migrate into a staging environment, validate, then promote.
Build the pipeline idempotent, keyed on WordPress IDs, so re-runs update instead of duplicating. You will re-run it - content keeps changing while you build.
Step 4: what happens to your frontend
Contentful replaces the WordPress backend, not the theme - the theme simply stops existing. Two realistic paths:
- Headless rebuild (the common one). A Next.js frontend consuming Contentful's delivery APIs - full control, modern performance, and often the reason the migration got scheduled at all. That project is its own scope; we've written it up in WordPress to React.
- Hybrid cutover. Move one surface first - the blog, the help center - onto the new stack while the rest of WordPress keeps running behind a routing layer. Slower in total, but de-risked, and the content team switches tools gradually.
Either way, plan render-parity checks: a script that diffs old and new pages for headings, links, images, and metadata catches transform bugs before readers do. Ours has flagged issues on every migration it's run.
Step 5: redirects and SEO preservation
The migration nobody notices is the successful one:
- 301 every changed URL from the audit's URL map - no chains, no 302s.
- Carry the metadata: titles, meta descriptions, canonicals, and social images become modeled fields in Contentful, not casualties of the HTML.
- Regenerate the sitemap from Contentful data and resubmit it in Search Console.
- Keep slugs stable where you can - the cheapest redirect is the one you don't need.
- Cut over behind the same domain and watch Search Console coverage and 404 reports daily for the first weeks.
Transform your UI for peak performance!
🔹
Unlock seamless, high-performance frontend solutions tailored to your business.
🔹
Get an interface that outshines competitors and delights your users.
The pitfalls we've actually hit
- Rich Text edge cases. Nested lists with embedded images, plugin-generated tables, marks spanning inline links - the last 5% of HTML takes 50% of the transform effort. Budget a manual-fix queue.
- Media embedded in HTML. Galleries and inline images that never existed in the media library need scraping, uploading, and re-linking as assets.
- Authors and relations. Authors, categories, and tags must exist as entries before the posts that reference them - import order matters.
- Scheduled and draft content. Posts scheduled mid-migration are the classic way to lose content; freeze publishing or run a delta pass at cutover.
- Date and timezone traps. WordPress stores local time, APIs speak UTC, and a naive conversion shifts every publish date by a day. Noon-anchored dates and explicit offsets have saved us more than once.
- Plain-URL internal links. Internal links imported as raw URLs break the first time a slug changes - resolve them to entry references during transform, not after.
Timeline and effort by site size
Site profile | Typical scope | Realistic timeline |
|---|---|---|
Blog or marketing site, up to ~500 posts, few custom fields | Modeling, scripted pipeline, redirects; frontend often rebuilt in parallel | 3-6 weeks |
Content-heavy site: thousands of posts, ACF and page builders, multiple types | Deep transform rules, manual-fix queue, phased cutover | 6-12 weeks |
Multi-site, multilingual, or enterprise | Localization modeling, workflows, per-market rollout | 3-6 months, phased |
What actually moves the number: page-builder content (the biggest multiplier), the count of distinct custom-field patterns, media volume, and how much frontend gets rebuilt in the same project - not raw post count.
When to bring in an agency: when the transform rules outgrow a weekend script, when organic traffic is the business and SEO risk is existential, or when the migration and the frontend rebuild land in the same quarter. That's the shape of project our Contentful development services team runs end to end - modeling, pipeline, frontend, cutover.
Or is a different headless CMS the better landing spot?
Worth asking before the pipeline gets built, because the export-and-transform work is largely identical whatever the destination - our guide to Contentful alternatives weighs the whole field, including when Contentful itself is the right landing spot:
- Contentful is the right landing spot for editorial organizations - teams with editors, workflows, and localization needs are exactly who it's built for.
- Payload is worth evaluating when the same project already includes a Next.js rebuild and you want the CMS self-hosted inside that codebase, with no per-seat fees - the trade is that you run it yourself. Full picture in Payload CMS: The Complete Guide.
- Sanity fits teams that want a hosted content backend with real-time collaborative editing - Sanity development services.
We build and migrate on all three. The destination is a team question, and it deserves ten minutes before the tooling gets written.
Planning a WordPress to Contentful migration?
We've built and run Contentful in production, and our migration tooling includes render-parity checks that catch transform bugs before your readers do. Book a call and bring your content inventory - or we'll help you build one.
FAQ
Alex Vasylenko is the founder of The Frontend Company, DBC and several other successful startups. A dynamic tech entrepreneur, he began his career as a frontend developer at Deloitte and Scandinavia's largest banking company. In 2023, Alex was honored as one of 'Top 10 Emerging Entrepreneurs' by USA Today.
Follow the expert:
LEARN MORE
