A headless migration replaces the machinery underneath your website while the site stays open for business, and it goes far deeper than a redesign with a fresh coat of paint. The pages your visitors see might look similar on launch day. What changes is everything behind them: where content lives, how it is structured, how it reaches the browser, and who can publish without filing a ticket.
That distinction matters because it explains both the upside and the risk. The upside is a marketing team that stops waiting on developers and a site that is fast by default. The risk is that you are moving every URL you have ever ranked for, and search engines do not forgive a sloppy move.
This is the complete picture of what a headless migration involves. Each section answers one question, and where a topic deserves its own deep dive, this post points you to it rather than repeating it.
What is a headless CMS migration?
A headless CMS migration moves a website off a traditional all-in-one platform, where content and presentation are welded together, onto a setup where the two are separate. The CMS becomes a content store that holds structured data. A separate frontend framework decides how that data becomes a page. The content survives the move. The presentation layer gets rebuilt.
In a traditional CMS like WordPress, Drupal, or TYPO3, the same system stores your content, renders the HTML, runs the plugins, and serves the page on every request. “Headless” means cutting the head off that body: the CMS keeps the content, and a framework like Astro or Next.js takes over rendering, usually producing static pages that a CDN serves directly. There is no PHP running per visit, no plugin chain to execute, no database query between a click and a page.
The split looks like this:
| Aspect | Traditional CMS | Headless setup |
|---|---|---|
| Content and presentation | Welded together in one system | Separated: a content store plus a frontend |
| Rendering | The CMS renders HTML on every request | A framework like Astro or Next.js renders, usually as static pages |
| Serving | PHP, plugins, and a database query per visit | Static pages served directly from a CDN |
| Examples | WordPress, Drupal, TYPO3 | A frontend framework over a structured content store |
The word “migration” is doing real work in that sentence. You are not starting fresh. You have a live site with history, rankings, and integrations, and all of it has to come across without breaking.
Why do companies migrate to headless?
Three reasons come up again and again:
- The team is slowed down by the CMS, waiting on developers for routine updates.
- The site is slow for visitors, and on a legacy stack that is structural rather than a tuning problem.
- Managing more than one market has become painful, with multilingual work fighting the platform.
A headless setup addresses all three at the architecture level rather than patching around them. The trigger is usually a marketing team that has run out of patience with how long routine work takes.
The editor experience is the quiet one. Most legacy setups were built for developers rather than for the people publishing on them every day, and the team pays that cost in time. We wrote about how editor experience determines whether a site succeeds and the signs your CMS is holding the marketing team back. If routine updates need a developer, that is the signal.
Performance is the measurable one. 49.5 percent of WordPress origins pass Core Web Vitals on mobile, against 69.8 percent of Astro origins, on July 2026 field data from the HTTP Archive Technology Report. The median WordPress site ships 119 KB of CSS on mobile before a single image loads, measured in the July 2025 crawl behind the HTTP Archive Web Almanac 2025. The architecture permits that gap rather than guaranteeing it, and we covered what decides the outcome in Core Web Vitals after migration.
Then there is multi-market work. Running one site across several languages on a traditional CMS tends to mean either duplicated installs or a tangle of plugins. Structured content handles this cleanly, which is why managing multilingual content at scale is one of the most common reasons a scale-up makes the move. If you are weighing the move against staying put, the case for a headless alternative lays out the trade-offs. Vendor uncertainty is a fourth trigger worth considering: what the Salesforce acquisition means for Contentful customers is the recent case in point: Salesforce completed its purchase of Contentful in September 2026, and Contentful customers now renew with a new owner.
What actually changes when you go headless?
The biggest change is that you start modeling content instead of typing it into a page. Every page type gets broken into structured components, the frontend becomes its own codebase with a build and deploy step, and hosting moves to a CDN. Editors gain a system that gets out of their way. The organization takes on a frontend that needs developers to maintain it.
It would be dishonest to pretend this is free. A headless setup has more moving parts than a single WordPress install. There is a content model to design, a frontend to build, and a deployment pipeline to run. The payoff is that each piece does one job well, but someone has to own the frontend after launch. That is a real consideration, and it is why we treat the part after launch as the hard part rather than the build itself. If Astro is the frontend direction you are considering, what Astro 7 changes for a marketing site is worth reading before you commit.
For editors, the day-to-day gets simpler. Content lives in clean, reusable blocks. There is no design mode to fight, no theme settings to break, no plugin that conflicts with another plugin. For the business, the trade is a system that holds up for years against one that needs rebuilding every couple of years.
How does a headless migration actually work, step by step?
A migration done properly moves through discovery, content architecture, design, build, and a staged go-live, with the client approving the plan before any building starts:
- Discovery: crawl and understand what you are migrating from.
- Content architecture: define what content lives on each page.
- Design: work from the approved content model rather than ahead of it.
- Build: develop against the approved design.
- Staged go-live: prove the system on real content, then cut over page by page.
The single rule underneath it is that the right work happens in the right order. Design before content architecture, or development before approved design, is how projects get redone halfway through.
We run every migration through the Essential Launch Framework: six phases, three client decision gates, and a proxy migration model that lets pages move one at a time instead of forcing one high-stakes launch. Rather than repeat the whole framework here, that post walks through each phase and why it exists.
The short version: you cannot plan a migration without first crawling and understanding what you are migrating from, you cannot design without knowing what content lives on each page, and you cannot safely cut over without proving the system works on real content first. Skipping any of those just moves the cost to a worse moment, usually weeks after launch.
The starting point of any migration is platform-specific. Most of the sites we move start on WordPress, and the WordPress to headless path covers the plugin chain, the export gotchas, and the redirect patterns unique to it. Webflow moves have their own shape, from CMS Collections to URL preservation, covered on the Webflow to headless page.
What is different about migrating off Wix?
Wix has no site export. Wix’s own documentation states that a Wix site needs to be hosted and operated on Wix’s servers, because the platform is a SaaS product built with Wix’s technology. One slice of your content comes off cleanly through a CSV export. Everything else gets read back off the live site.
| What you have | How it comes off Wix |
|---|---|
| CMS collections | A CSV export, one collection at a time, including hidden and system fields. Time fields arrive as UTC+0 |
| Blog posts | A CSV export of the read-only collection behind the blog, carrying the post text without its formatting. Wix still lists export to another platform as an open feature request |
| Design and layout | Nothing to export. The rendered page is the only specification of your design that exists |
| Media | Pulled off the Wix CDN during the crawl, at the crop each image is served at today |
The blog is the part teams underestimate. Posts can still be recovered through Wix’s Blog API, which returns the post body when you ask for it explicitly. That is developer work, and it needs its own phase in the plan.
URLs are more predictable. Wix puts blog posts under a /post/ prefix by default, one level below the blog page itself, so the redirect map for the blog falls out of the post list. Dynamic pages driven by a CMS collection follow a URL pattern, so enumerate them from the collection data first.
Wix is good at the thing it was built for, which is running a site without a developer. The exit is expensive for exactly that reason. The full path, including Velo code and dynamic pages, is on the Wix to headless migration page.
What is different about migrating off Squarespace?
Squarespace does have an export, and it produces a single .xml file that carries less than your site does. Layout pages, text and image blocks, and one blog page with its posts come across. Squarespace names the rest on a no-export list, and all of it gets rebuilt from the live site.
What the file leaves behind, per Squarespace’s own documentation:
- Every blog page after the first. Only one exports.
- Album, cover, index, info, calendar, portfolio and store pages.
- Style settings and custom CSS, so your design has to be read off the live site and rebuilt in code.
- Audio blocks, video blocks, product blocks, drafts, and content in page-specific headers, footers and sidebars.
- Your images as files. The export points at them by URL, and Squarespace states that when you deactivate your Squarespace site, the image links also deactivate. Download the media while the site is still live, because Squarespace will not export from a site that is not active and published.
URLs need their own pass. A collection item sits at the collection slug plus the item slug, so a post lands at /blog/example-post. The blog post URL format is a site-wide setting with date and title variables, and Squarespace states that changing it does not retroactively change existing posts. A blog running for years often carries two or three URL shapes, so build the redirect map from a crawl. Changing a slug does not redirect the old address either, and Squarespace’s documentation is blunt about the result: a 404 appears.
Running the export takes minutes. Establishing how much of the site sits outside it is the actual scoping job. There is no content API to fall back on either. The Squarespace developer platform covers commerce, webhooks and reseller provisioning. The detail is on the Squarespace to headless migration page.
What is different about migrating off Webflow?
Webflow has two exports and they cover different halves of the site. Code export produces a ZIP of the HTML, CSS, JavaScript and Assets panel images, with the CMS left out, so an exported site renders Collection lists as the empty state and Collection pages without their field-bound content. Only the primary locale is in there, and code export is a Workspace plan feature that Site plans do not include. Content leaves separately, one Collection at a time, as CSV.
| What you have | How it comes off Webflow |
|---|---|
| Collection items | A CSV per Collection, archived items included, carrying the Item ID Webflow uses to match rows |
| Rich text | Exports as HTML, so the markup survives |
| References | Plain text or URLs, like most field content. Multi-reference fields become a comma separated list |
| Images and files | Webflow-hosted URLs, not the files themselves, and Webflow warns they break if you delete the site |
| Locales | One export per locale. The CSV carries only the locale you are viewing |
Download the media while the Webflow site is still published. The Data API is the other route into the content, capped at 100 items per request. Staged and published items sit on separate endpoints, and locales are selected by ID.
URLs follow a rule you can enumerate. Each Collection has a Collection URL, the folder slug sitting in front of every item, so a Blog Posts Collection with the Collection URL post puts its items at /post/your-blog-post. Webflow also exports your existing 301 redirects to CSV, which hands you the redirect history the site already has. Those rules are relative to the root domain and do not apply to localized slugs, so a multi-locale site needs a second pass.
Webflow is good at what it was built for, which is letting a designer run a site without a developer. Getting out means running the design and the content as two separate jobs, because Webflow sends them through two separate doors. The full path is on the Webflow to headless migration page.
What is different about migrating off Sitecore?
Sitecore has no single export file, and which routes out you have depends on the product. XM is the content management core, XP is XM plus the xConnect and xDB marketing stack, and XM Cloud documents the Authoring and Management GraphQL API at /sitecore/api/authoring/graphql/v1/.
| What you have | How it comes off Sitecore |
|---|---|
| The item tree | The ItemService REST API reads an item by ID or path, its children, or a search result, with language and paging parameters. Its default security policy denies remote clients, so it gets switched on first |
| Templates and renderings | Sitecore Content Serialization writes YAML files into paths you name in a module file. Sitecore’s own XM Cloud guidance is to serialize developer-controlled items rather than the content tree |
| Versions and languages | The Master database holds all versions of all content. The Web database holds only what was published to that target |
| Presentation | XML in two fields. The Renderings field is shared across languages and versions, the Final Renderings field is versioned, and the two get merged at render time |
| The Media Library | Each upload is a blob plus a media item holding size, height, width and blob ID. The blobs sit in SQL by default, or in Azure Blob Storage |
Language fallback does not survive a flat export. An item can exist in ten languages with content in two, the rest falling back to another language at item or field level, so count what is actually translated before you scope the move.
URLs are assembled from the item path plus a handful of settings, so the map comes out of configuration. useDisplayName decides whether the display name or the item name goes in the URL and is false by default, languageEmbedding takes asNeeded, always or never, and languageLocation puts the language in the path or a query string. Aliases sit outside all of that. An alias lets one content item answer on any number of extra URLs, and Sitecore’s documentation notes that this can confuse search engines. Each one is a live URL that needs a redirect.
Sitecore is good at what it was built for, which is running large multi-site, multi-language estates with editorial workflow and role separation. Getting out means treating the item tree, the presentation XML and the URL configuration as three separate jobs. The detail is on the Sitecore to headless migration page.
What is the biggest risk in a headless migration?
Losing your search traffic. The redirect map is what decides it, more than the design, the CMS choice, or the build. A site that has been live for years has accumulated ranking signals across hundreds or thousands of URLs, and a poorly planned move can erase that in a single deployment. The fix is treating redirects as a first phase deliverable rather than a launch-week checklist item.
A 301 redirect tells search engines a page has permanently moved, and Google confirms that 301 and 302 redirects do not cause a loss in PageRank. The equity transfers, but only if the redirect exists. A missing one means Google hits a 404 and that equity is gone. The most damaging mistake we see is redirecting every old URL to the new homepage, which Google treats as a soft 404 and ignores.
This is the part that most rewards care, so it gets its own deep dive in the redirect strategy that preserves your traffic. The first weeks after launch are where gaps surface, and what to watch in the first 30 days covers the monitoring that catches them while they are still fixable.
How long does a headless migration take?
Plan for 12 to 18 weeks from discovery to go-live for a typical project, then a separate window for search engines to catch up. The project timeline depends on how many page types, languages, and integrations are in scope. The reindexing timeline is out of your hands and runs in parallel after launch.
Search engines reprocess a move on their own clock, and how long that takes is not something you can plan around precisely. What you can plan around is Google’s own guidance, which is to keep redirects live for at least a year. The redirects need to stay live through the entire window, well past the point where the new site looks settled.
A short traffic dip in the first week or two is normal as Google works through the redirects. A dip that is still deepening in week three is a problem, usually a gap in the redirect map.
How much does a headless migration cost?
A full migration has a fixed project fee, scaled to the number of page types, languages, and integrations. Ongoing technical ownership after launch is separate, billed monthly, and it is optional.
Fixed pricing matters more than the number itself. Hourly billing on a migration creates an incentive to draw the work out and turns every scope question into an invoice. A fixed price set after a proper scoping pass means the budget is known before the build starts. The full breakdown of what each tier includes is on the headless migration service page.
If a migration loses 30 percent of organic traffic and that traffic feeds your pipeline, the cost of getting it wrong dwarfs the project fee. That is the real economics of the decision.
How do you migrate without losing your search rankings?
The sequence that protects rankings:
- Crawl every URL first.
- Identify the ones with traffic or backlinks.
- Map each to its new home one to one.
- Implement the redirects server-side as 301s.
- Test the full list against the new site before launch.
- Watch the indexing report and 404s for the first month.
Rankings survive a migration when the redirect map is complete and the monitoring catches what slipped through.
Server-side 301s are the only reliable option. Client-side redirects through JavaScript or meta refresh are unreliable for search engines, and redirect chains, where A points to B points to C, add latency and weaken the signal at every hop. Google follows up to ten hops but recommends pointing A straight to its final destination.
We have seen a redesigned site lose 40 percent of organic traffic within two weeks, and the cause was never the design. It was a redirect map nobody treated as a priority. The proof that it can go the other way is the Eversports migration: WordPress to Storyblok across six languages, a site roughly ten times faster, with rankings intact.
Is a headless migration the right move for you?
It is the right move if:
- your team is blocked by the CMS
- your site is slow
- you are managing more than one market and the current setup makes that harder than it should be
It is the wrong move if:
- you have a small static site that rarely changes
- you have no internal team to own a frontend after launch
The honest answer depends on what you are working with today, and the work is different depending on where you are starting from. We have written up what the move looks like from WordPress, Webflow, Wix, Squarespace, Drupal, TYPO3, Umbraco, Sitecore, Kentico and Contentful.
The way to find out without committing to a full project is a headless audit. We crawl your current site, measure where it actually stands on performance, map the migration scope including the redirect work, and tell you whether a move is worth it. If it is not, we say so. If it is, you start the migration with the scope already understood and the budget already fixed, which is the difference between a project that lands on time and one that does not.