WordPress to Hygraph (GraphCMS) Migration Guide

WordPress is a capable monolith, but it couples your content to a PHP rendering layer, a MySQL schema you rarely control, and a plugin ecosystem that fights you as traffic scales. When your team wants a fast decoupled front end, multichannel delivery, or a schema you actually design, moving to Hygraph (formerly GraphCMS) is a compelling next step. Hygraph is an API-first, GraphQL-native headless CMS with a federated content layer, and it treats content as structured data rather than a stream of HTML.

This guide walks through why teams go headless from WordPress, what changes architecturally, how to model content and wire up the API, the concrete migration steps, and how to preserve the SEO equity you have spent years building. The goal is a clean cutover with no ranking loss and a front end that renders in milliseconds.

Before you touch a single export file, understand that this is a re-platforming project, not a plugin swap. Content, URLs, media, and rendering all move to new systems. Treat it with the same rigor as any website migration project, because the risks (broken links, lost rankings, missing redirects) are identical.

Why Go Headless From WordPress

WordPress renders pages server-side from templates, which tightly binds your content to your presentation. That works until you need to serve the same content to a web app, a mobile app, a kiosk, and a partner API. Going headless separates the content repository from the presentation layer, so you author once and deliver everywhere through a single GraphQL endpoint.

• Performance: A statically generated or edge-rendered front end (Next.js, Astro, Nuxt) served from a CDN is dramatically faster than PHP rendering plus a stack of caching plugins.
• Security surface: No public /wp-admin, no plugin CVEs, no PHP execution on your edge. Hygraph hosts the content; your front end is just static assets and API calls.
• Developer experience: A typed GraphQL schema, content federation across sources, and preview APIs beat wrangling ACF and the loop.
• Scalability: Hygraph's read replicas and CDN-cached queries absorb traffic spikes that would topple a shared-hosting WordPress box.

If you are still weighing the tradeoffs, our breakdown of headless CMS vs traditional CMS covers when the decoupled model pays off and when a monolith is genuinely the better call. Headless is not free: you take on front-end build responsibility and lose WordPress's plug-and-play themes.

The Decoupled Architecture and What Changes

In WordPress, one application does everything: stores content, runs business logic, and renders HTML. In a Hygraph setup, those responsibilities split into distinct layers, and this is the single biggest mental shift for your team.

• Content layer (Hygraph): Your models, entries, assets, and localization live here, exposed through an auto-generated GraphQL API with granular permissions and mutation endpoints.
• Presentation layer (your front end): A framework like Next.js queries Hygraph at build time (SSG), request time (SSR), or on-demand (ISR/webhook revalidation), then renders and ships to a CDN.
• Delivery layer (CDN/edge): Cached HTML and assets served globally, revalidated when Hygraph fires a webhook on publish.

What you lose: WordPress themes, shortcodes, the visual customizer, and any plugin that rendered output (contact forms, sliders, related-posts widgets). Those become front-end components or third-party services. What you gain: content you can query precisely, no N+1 template queries, and preview environments that mirror production. Dynamic functionality that used to be a plugin often becomes a small serverless function or a piece of custom development wired into your CRM or commerce backend.

Content Modeling and API Setup

WordPress hides its data model behind wp_posts and wp_postmeta, where everything is a "post" and metadata is loosely typed key/value rows. Hygraph asks you to design an explicit schema, and this is where migration quality is won or lost. Map your WordPress content types before exporting anything.

• Models: Create a model per content type: Post, Page, Author, Category, Tag. Custom post types and ACF field groups become their own models with typed fields.
• Fields: Translate the WordPress fields deliberately: title to a String, body to Hygraph's Rich Text (RTF) field, slug to a slug/String, publish date to DateTime, featured image to an Asset reference.
• Relations: Replace taxonomy joins with real references. A Post references one or many Categories and an Author, giving you type-safe queries instead of taxonomy meta lookups.
• Components and enumerations: Repeating structures (FAQ items, CTA blocks, SEO metadata) become reusable components. Model an SEO component with metaTitle, metaDescription, canonicalUrl, and ogImage and attach it to every page-like model.
• Localization: If you run WPML/Polylang, enable Hygraph localization on the relevant fields rather than duplicating entries.

Once models exist, Hygraph auto-generates the GraphQL schema. Set up two API access approaches: a Content API token with read scope for your front end, and a Management/Mutation token with create/publish scope for the import scripts. Note Hygraph's rate limits and use its bulk mutation API so you do not throttle mid-import.

The Step-by-Step Migration

With models in place, execute the migration as a repeatable, scriptable pipeline rather than a one-time manual copy. You will run it more than once.

• 1. Export from WordPress: Pull content via the WordPress REST API (/wp-json/wp/v2/posts, /pages, /media, /categories) rather than the XML dump. JSON with embedded relations is far easier to transform than WXR.
• 2. Transform: Write a script (Node/Python) that maps each WordPress record to a Hygraph create mutation. Convert post_content HTML to Hygraph Rich Text using their AST/HTML-to-RTF helper, resolve author and category IDs to references, and normalize slugs.
• 3. Migrate media: Download every image from wp-content/uploads and upload to Hygraph Assets via the asset API, keeping a map of old URL to new asset ID. Rewrite in-body image src attributes to the new asset URLs during transformation.
• 4. Load: Run batched createPost/createPage mutations, then publish. Do a small pilot batch (10-20 entries) first, validate rich text and relations rendered correctly, then run the full set.
• 5. Build the front end: Query Hygraph from your framework, recreate templates as components, and match the existing URL structure exactly.
• 6. Wire webhooks: Configure Hygraph publish webhooks to trigger front-end rebuilds or ISR revalidation so editors see changes go live.

Run the transform script idempotently against a staging Hygraph environment so you can re-import cleanly as you fix mapping bugs. Only promote to your production project once a full pilot verifies content fidelity end to end.

SEO Preservation During the Cutover

The fastest way to tank a migration is to change URLs or drop metadata. Because your slugs are moving from WordPress's permalink structure into Hygraph fields, you must guarantee URL parity and carry every scrap of on-page SEO across.

• Preserve URLs: Store the exact existing path on each entry and route your front end to match. If any URL must change, that path needs a 301. Build a complete 301 redirect map before launch and implement it at the edge (Next.js redirects, Vercel/Netlify config, or a CDN rule).
• Carry metadata: Yoast/RankMath titles, descriptions, canonical tags, and Open Graph data live in postmeta. Export them into your Hygraph SEO component so nothing is regenerated from defaults.
• Structured data: Recreate Article, BreadcrumbList, and Organization JSON-LD in your front-end components; it will not migrate automatically.
• Sitemap and robots: Generate a fresh XML sitemap from Hygraph content and submit it in Search Console the day you cut over.

Work through a full website migration SEO checklist before and after launch, and keep the old WordPress instance reachable (unlinked, on a subdomain) until Google has recrawled and rankings hold steady. Monitor Search Console coverage and crawl stats daily for the first few weeks so you catch any 404 spikes immediately.

Testing, Cutover, and Rollout

Never flip DNS on a hunch. Stage the entire stack, validate it against production data, and cut over during low traffic with a rollback path ready.

• Content QA: Spot-check rich text rendering, image loading, internal links, and localized entries across a representative sample of migrated pages.
• Redirect testing: Crawl the old sitemap with a tool like Screaming Frog and confirm every URL returns 200 or a single 301 to the right destination, with no chains or loops.
• Performance baseline: Measure Core Web Vitals on the new front end; a headless build should comfortably beat the old WordPress LCP.
• Cutover: Point DNS to the new front end, submit the sitemap, and keep webhooks live so editorial changes flow immediately.

A disciplined pipeline (REST export, scripted transform, staged Hygraph environment, verified redirects) turns a scary re-platform into a controlled, repeatable process. The payoff is a faster, more secure, API-driven publishing stack your team can extend for years.