Gatsby to WordPress: Migrating GraphQL Sites to a Real CMS

Gatsby pioneered the idea that a static site could feel like a full-stack application: GraphQL for data, React for rendering, a rich plugin ecosystem for everything else. That vision was ahead of its time and has aged into a maintenance burden for many teams. Build times balloon as content grows. Plugin compatibility drifts across major versions. Contributors have to learn GraphQL to add a blog post. WordPress removes those frictions. Content lives in a database, edits happen in a browser, and publishes are instant. Migrating a Gatsby site to WordPress keeps everything the frontend produced — the same layouts, the same images, the same components — while replacing the build-heavy content workflow with WordPress's editor. The second reason is ecosystem convergence. Gatsby Cloud shut down. Plugin maintenance across the Gatsby ecosystem has slowed. WordPress meanwhile continues to grow and continues to receive security patches from a foundation with clear long-term commitment. For a site expected to run for years, the WordPress platform is more predictable.

The pipeline runs `gatsby build` and consumes the `public/` output. Every page becomes a WordPress template. GatsbyImage output — the srcset variants, the blur-up placeholders, the lazy loading — ships intact. MDX content renders to HTML during the build, and that HTML becomes WordPress post content. React components compile into the bundle and hydrate against the pre-rendered DOM inside the theme. Reach Router (or React Router, depending on your Gatsby version) becomes WordPress's rewrite engine so URLs stay identical. Plugins that emitted scripts at build time (analytics, gtag, hotjar) carry over as inline scripts in the theme header or footer. What does not carry over is anything that required Gatsby's node APIs at request time — dynamic routes with server-side data fetching in preview mode, or scheduled builds triggered by webhooks. Those get replaced by WordPress's native scheduling and editor preview.

Run `gatsby clean && gatsby build` locally. If the build succeeds, you are ready. If it fails on a missing environment variable, add stubs to `.env.production` so the build has something to substitute — the real values can go into WordPress after migration. Audit gatsby-config.js for plugins that hit external APIs at build time. If those APIs are behind auth (source-wordpress, source-contentful with private keys), make sure the credentials are available where the pipeline runs. Uploading a GitHub repo lets you set the credentials as environment variables in the conversion settings; a ZIP upload requires the credentials to be in `.env`. Check for known-slow plugins. gatsby-plugin-sharp with thousands of source images can push builds past the pipeline's default timeout. If you know your build is slow, contact support before uploading so we can allocate extra time.

Upload your ZIP or connect GitHub. The pipeline detects Gatsby, runs the build, and consumes `public/`. Because Gatsby is a pure static site generator, headless Chrome only runs a validation pass. Every HTML file becomes a WordPress page or template. Assets get rewritten from Gatsby's hashed paths to the WordPress theme convention. GraphQL query results that were interpolated into the HTML stay interpolated — the theme has no GraphQL runtime, just static content. For sites that were sourcing from an existing WordPress instance via gatsby-source-wordpress, the migration is essentially replacing the Gatsby frontend with a WordPress theme that renders the same content directly. The GraphQL indirection goes away.

Install Yoast or Rank Math. Your Gatsby site probably used react-helmet or gatsby-plugin-react-helmet to manage meta; those tags survive in the initial HTML but editors need a WordPress plugin to change them without touching code. Install a caching plugin. Gatsby's core selling point was speed via static output, and WordPress with a caching plugin serves cached HTML equally fast. Set up SMTP. Gatsby often relied on Netlify Forms or third-party form endpoints for contact submissions. Contact Form 7 with WP Mail SMTP gives you a WordPress-native equivalent that emails you directly. Redirect the old build's URLs. If you were on Netlify with a _redirects file, translate those rules into the Redirection plugin or add them to .htaccess directly.

Do not migrate without a fresh gatsby build. Old cached builds sometimes contain stale content that the pipeline captures, giving you a WordPress theme with last month's copy. Do not skip the audit of runtime plugins. Anything that ran on Gatsby Cloud or Gatsby's Node server needs a WordPress replacement, and finding out post-migration is worse than finding out during preview. Do not forget internationalization. If you used gatsby-plugin-react-i18next with per-locale routes, migrate one locale at a time and combine with WPML or Polylang. Do run the free preview. Gatsby's image handling is thorough enough that pre-render results usually match perfectly, but the preview is the moment to confirm.

Upload on the homepage or connect GitHub. Preview the WordPress render for free before paying. Conversion typically takes five to eight minutes depending on how many images your build processes.