Drupal to Headless Migration: A Complete Playbook

Migrating Drupal to headless is one of the most common projects we’re hired for, and it’s also the one where we see the most half-finished, half-working results when teams try it themselves. The architecture is solid. The failure mode is almost always in the execution — teams underestimate preview, SEO, content migration edge cases, and cutover complexity.

This guide is the migration playbook we actually use. It’s opinionated and specific. If you’re considering a headless migration, read this before you scope the project — it’ll save you from the three or four mistakes that turn a 12-week migration into a 24-week migration.

For background on what decoupled Drupal is, see What is Decoupled Drupal?. For how to connect Drupal to React specifically, see Drupal and React: The Complete Guide.

Before you start: is headless even right for you?

We’ll say this up front because it’s the most expensive mistake to make: not every Drupal site should be migrated to headless. The question isn’t “would headless be better?” The question is “is headless enough better to justify the cost and risk?”

Headless migration is usually the right call when:

You have a modern frontend team and the existing Drupal theme is painful to maintain.
You need performance or DX wins that Drupal’s render pipeline can’t give you.
You’re also rebranding or redesigning (migration pairs well with redesign because you’re touching everything anyway).
Your content model is worth preserving — you’re not just running a blog.

Headless is usually the wrong call when:

Your Drupal site works fine and the pain is exaggerated. “Our theme is annoying” is not the same as “our site is broken.”
You don’t have frontend engineers to own the React/Next.js frontend after launch.
You’re already struggling with content model complexity. Moving to headless won’t fix that; it’ll expose it.
You’re on a hard deadline driven by something other than the migration itself. Headless migrations take longer than expected, always.

If you’re still sure headless is right after that filter, read on.

The four-phase playbook

Every successful headless migration we’ve done follows roughly the same four phases. The timelines are for an 8-12 week engagement on a mid-sized site (a few hundred pages, standard content types, no weird custom logic). Bigger sites and more complex ones scale up proportionally.

Phase 1: Audit and scope (weeks 1-2)

Before any code gets written, we map the existing site in detail. The output is a migration plan document that everyone — dev team, editors, stakeholders — agrees on.

What gets audited:

Content types and fields. Every content type, every field, every reference. Mark which ones are used in production and which are legacy clutter.
Content volume. Total nodes, revisions, media items, users. Archived content counts too — you have to decide what to migrate and what to leave behind.
Custom modules. List every custom module and categorize: “business logic we need to keep,” “hacks we can delete,” “things that need to be rewritten in the frontend.”
Theme overrides. Preprocess functions, Twig templates, theme-specific behavior. Most of this won’t survive the migration, but some of it encodes real behavior that needs to be preserved elsewhere.
Third-party integrations. CRM sync, marketing tools, payment, search, analytics. Each one needs a plan: stays on Drupal, moves to frontend, gets replaced, or gets deleted.
SEO assets. Existing redirects, canonicals, structured data, sitemap, robots, meta tag logic. All of this has to survive the migration or you’ll lose traffic.
URLs. The full URL map. Which URLs are canonical, which are aliases, which are redirects from older content. Preserving URL continuity is the #1 SEO-critical task in a migration.

Output: A document that answers, for every piece of the existing site: “what happens to it in the migration?” Keep it, move it, rebuild it, delete it, replace it. Get sign-off from stakeholders before moving on.

Phase 2: Parallel build (weeks 3-8)

The new frontend gets built on a staging environment alongside the existing Drupal site. The old site stays live. Nothing breaks in production.

What happens in parallel build:

Set up Drupal for headless. Enable jsonapi, tune the API exposure (hide entities you don’t want exposed, fine-tune includes), set up CORS, deploy the next module for preview tunneling.
Build the frontend. New Next.js / Astro / Vite app consuming the Drupal API. Implement the page templates, routing, components, preview mode, and 404 handling.
Content model adjustments. Sometimes the existing content model doesn’t map cleanly to the API. You might need to flatten deep Paragraph structures, or add helper fields to make API responses cleaner. Do these changes now — before content migration.
Migrate a subset of content. Don’t migrate everything yet. Migrate 10-20 representative pages (home, top landing pages, a couple blog posts, a page with every Paragraph type you support) and use them to validate the frontend implementation.
Preview flow. Build the editor preview tunnel — draft content in Drupal, click “Preview,” land on the staging frontend with an authenticated preview token, see the draft rendered. This is the single most underestimated part of a headless migration. Budget 1-2 weeks for preview alone.
SEO infrastructure. Rebuild the sitemap, redirects, meta tags, and structured data in the new frontend. Don’t wait for launch to do this.

Output: A staging site at staging.yoursite.com where stakeholders can click around a representative version of the new site with real content. Not everything works yet, but the structure is there.

Phase 3: Content migration (weeks 9-10)

Now we migrate the full content set from the old site to the new architecture.

What happens in content migration:

Content model mapping. For every old content type / field, where does it go in the new model? If the new content model is identical, this is trivial. If you’re restructuring during the migration (common), write Drupal Migrate API config or a custom migration script to map old → new.
Media migration. Move files and images into the new media library. Update file URLs. Set up image styles for the responsive images the new frontend needs.
URL preservation. For every old URL, decide: (a) same path in the new site, (b) different path + add a 301 redirect, or (c) delete + serve a 410 or 404. Build the redirect table before cutover, not after.
User accounts. If the site has logged-in users, decide whether accounts move to the new system and how auth works going forward. This often becomes its own sub-project — budget accordingly.
Testing content migrations. Migrate to a dev environment first. Compare 50 random pages old vs new and look for missing fields, broken images, or formatting differences. Fix, re-migrate, repeat until clean.

Output: A staging site with all content migrated and all redirects in place. Editors can log in, edit, preview, and publish. QA can click through the site and find bugs.

Phase 4: Cutover and stabilization (weeks 11-12)

Cutover day:

Content freeze. Editors stop publishing to the old Drupal site. Any in-flight edits get held.
Final content sync. Run the migration one last time to catch anything added since the last sync.
DNS flip. Point yoursite.com at the new frontend. The old Drupal site moves to admin.yoursite.com for editor access.
Redirects live. All 301s from old URLs to new URLs start returning correctly.
Resume publishing. Editors can publish again, now to the new system.
Monitoring. Watch Core Web Vitals, error rates, and GSC crawl stats closely for the next 48 hours.

Post-launch stabilization (2 weeks):

Fix whatever breaks. Something will break. Plan for it.
Resubmit sitemap to Google Search Console.
Monitor search traffic daily. Expect a 10-30% dip in impressions for 2-4 weeks — this is normal. If the dip is worse than 30% or lasts longer than 4 weeks, you have an SEO problem to investigate.
Capture lessons learned in a document for future migrations.

The SEO part (read this even if you skip everything else)

URL continuity is the single biggest SEO lever in a migration. If you do nothing else correctly, get this right:

Every old URL either keeps the same path or redirects (301) to a specific new URL. No wildcard redirects, no “just 301 everything to the homepage,” no silent 404s.
Meta titles, meta descriptions, and canonical tags migrate. If a page had a hand-crafted meta description on the old site, it should have the same one on the new site.
Structured data migrates. If you had Article schema, Organization schema, or BreadcrumbList schema on the old site, rebuild it in the new frontend.
Sitemap gets regenerated and resubmitted. Make sure it only includes the new URLs, not the old ones.
robots.txt gets updated. Point at the new sitemap. Disallow any admin paths that shouldn’t be indexed.
Google Search Console gets the new URLs. Submit the sitemap manually on launch day. Request indexing for the top 10-20 pages.

Expect a search traffic dip of 10-30% for 2-4 weeks regardless. Google re-crawls, re-evaluates, and eventually converges. If you skip redirects, the dip is 60%+ and lasts for months.

What goes wrong (and how to avoid it)

Preview discovered at week 8. Team builds the frontend for 6 weeks, editors show up to review, realize they can’t preview drafts, and the project goes into crisis mode. Fix: build preview in week 3.

Content model surprise. Midway through migration, team realizes a specific content type has 400 variations of a field config that the new model doesn’t handle. Fix: audit content types thoroughly in phase 1 and run a test migration of a representative sample early.

Missing redirects. Old URL /2023/an-article-slug doesn’t exist in the new site and nobody thought to add a redirect. 404 in search results. Fix: generate the full redirect map in phase 3 and test it on staging before cutover.

Image URL rewriting missed. Images still load from drupal.yoursite.com after launch. CDN strategy breaks. Fix: set up the asset proxy or rewrite rules in phase 2, not after launch.

Auth flow untested. Logged-in users get redirected to the wrong place after login because auth moved from Drupal to the frontend mid-project. Fix: test logged-in user flows in QA, not just anonymous browsing.

Cutover on a Friday afternoon. Something breaks over the weekend, nobody’s on call. Fix: cutover on a Tuesday or Wednesday morning when the whole team is available.

Realistic timelines and costs

For a mid-sized Drupal site (few hundred pages, standard content types, no weird custom logic):

Timeline: 10-14 weeks, including content migration and 2 weeks of stabilization.
Cost: $50k-200k depending on content volume, custom logic complexity, and redesign scope.
Team: 1 backend Drupal dev + 1-2 frontend devs + 1 project lead. Plus design if you’re redesigning.
Post-launch: Budget 10-20 hours/month for the first 3 months for stabilization and small fixes.

Bigger sites (1000+ pages, multilingual, complex permissions, heavy custom logic) go up from there. 20+ week engagements aren’t unusual for enterprise sites.

TL;DR

Migrating Drupal to headless is a real engineering project with well-understood phases: audit, parallel build, content migration, cutover. The architecture is solid and the outcome is worth it for the right sites. But the execution is where projects fail — specifically on preview infrastructure, URL continuity for SEO, and asset URL rewriting. Get those three things right and the rest is tractable.

We migrate Drupal sites to headless for a living. If you’re scoping a migration and want an honest audit before you commit — we do free 30-minute audit calls.