A Guide to a Successful Headless CMS Migration

The most common website upgrade path entails a Headless CMS migration from a traditional CMS like WordPress. However, it is not just a simple “lift and shift” process. It is better served as part of a carefully planned wider strategic review as this short blog explores.

Alan Gleeson - CMO Contento

Alan Gleeson

Co-Founder / CEO

January 8, 2024

Grey Ellipse Icon

5min read

Man sitting at desk looking at computer screen

Key Considerations When Migrating to a Headless CMS

In recent years, we’ve witnessed a growing trend for scaling companies to transition away from traditional CMS like WordPress to Headless CMS like Contento. While still in their infancy, headless CMS-backed websites are becoming increasingly popular, especially for high-performance websites where the attractions of a bespoke design, omnichannel delivery, blazingly quick speeds, the lack of vendor lock-in, and scalability, collectively represent a compelling value proposition.

An ideal CMS migration occurs when the replatforming is part of a much bigger project e.g.  a website update with external expertise supporting it. Perhaps a newly designed site is being built from scratch, with a brand new visual identity being rolled out, and a messaging update. 

However, many migrations also take place without including other enhancements be that a visual design uplift or messaging updates. These may be due to push factors such as issues with WordPress (the most popular traditional CMS) which mean that a shift is inevitable. With these types of migration you are essentially swapping out the back end, so it is important that expectations are set accordingly. You're also swapping out quite a lot of the front end too if it's a PHP/traditional CMS to headless. So all of your WordPress page templates, for example, would need to be rebuilt (not just 'plugged in' to another CMS).

Regardless of the project scope, a traditional CMS migration to Headless is not a trivial exercise, and this article is designed to share some of the wider elements to be aware of so as to avoid any “nasty surprises”.

Despite some of the challenges outlined below, traditional to Headless CMS migrations will likely continue at pace, as a wider audience starts to better understand the advantages of Headless.

A Headless CMS Migration

Before you commence the migration process it is important to be clear on the reasons for the move. Like any change there will likely be some resistance to it - hence you need a compelling motivation to make the migration. 

What are you hoping to achieve by the move? 

The following represent some of the more common reasons companies move to Headless. For the right use case the advantages are pretty compelling.

1- Performance Gains

A primary driver of a CMS migration is performance related e.g. “improving the site speed”. 

The ideal scenario for this is a high-traffic site where even marginal gains in site speed will materially impact the bottom line. This explains why so many major consumer brands have made the leap - performance gains achievable on a Headless CMS infrastructure trump the gains from a super optimized traditional CMS.

However, for smaller traffic websites, speed gains are unlikely to move the needle sufficiently to warrant a move without additional factors in play. 

Finally, it is worth flagging that performance gains are also dependent on other factors beyond just the CMS and underlying infrastructure. High res images, video and animations often represent key elements that negatively impact performance if they are not optimized in parallel. 

2- Scalability Challenges

Another primary driver of change is when a company reaches the limit of its capabilities with its current tech stack (often WordPress). This push factor is a powerful one - the internal frustration of continuing on WordPress simply becomes too much to bear. 

3- Bespoke Web Design

Some companies put a premium on beautifully designed bespoke websites that are not constrained by templates. This represents a key driver for premium brands, where designers want free reign at building a highly functioning website optimized to convert without being constrained by CMS limitations. It is also worth noting that design is not just the aesthetics/ branding, but also decisions related to everything from what is the best navigational model, or content hierarchy, for YOUR company and your audience. 

Finally, the idea of 'bespoke' design is not as a luxury that only large companies can afford because they have cash to burn, but something that every growing company needs, and deserves, from the very start.

4- Omni Channel Capability

Many of the early adopters of Headless were companies seeking a “single version of the truth”, and who were required to manage content serving “different heads” or channels. This is a strong driver (particularly for B2C and eCommerce companies) who need a strong and consistent presence in different channels.

5- Future Proof Your Tech Stack

A less common motivation but one that some tech leaders will be attracted to is the fact that a Headless infrastructure is flexible, scaleable and future proof. For those willing to look a little further down the road, choosing an infrastructure with longevity ensures that painful downstream migrations are avoided. Not only is it easier to get data out of a Headless CMS, but it is also much easier to swap components out as technology evolves. Hence, for early adopters who have a bias for cutting edge technology and “best of breed” solutions a bespoke site on a Headless infrastructure represents a state of the art combination.

6- Enhanced Security

For those websites where security is a primary requirement, known security vulnerabilities with platforms like WordPress (primarily the plugin reliance) mean that a migration to a Headless CMS offers a more secure infrastructure.


As is evident from the list of advantages, the benefit set for Headless is compelling for the right context. That said, you still need to be clear on the motivations to change and the goals of the “traditional to Headless migration” to ensure it meets its expectations. 

In short, you need to answer:

  • What problems is your organization facing with its current website or platform?

  • Which of these problems are you trying to solve by going headless?

  • How will migrating to a headless CMS solve them?

Once you are clear on these you can commence the process in confidence. For measurable SMART objectives, like “performance”, it is worth defining the criteria by which you intend to evaluate your newly constructed system, such as metrics for page load speed so it is clear on specific gains you are targeting.

Finally, it is worth noting that the combined benefits for bigger websites are really compelling, which explains its increased popularity. For lower traffic websites (which often equates to smaller teams and budgets) the key is to ensure the motivations to change are clear.

Additional Headless CMS Migration Factors

So what are some of the additional factors that you need to consider as you assess the scale of the migration you are planning?

1- Data Migration & Content Modelling

Do the data structures you are pulling out of the old CMS from your current content models make sense to be used in the same way in the future? 

Reviewing your current content models along-side your long term content plans should be a major part of the planning of the data migration. 

For example, if omnichannel is one of the main drivers, are you able to reuse the same data in multiple different heads effectively or do you need to tweak your content models to better facilitate this?

This could entail tasks such as a content cleanup, segmentation into smaller units, merging with other relevant data or creating new models that better facilitate your long term content plans.

If done correctly, good content models set the foundations for long term scalability, omnichannel usage, less repetition of data across platforms and ultimately less work for your content team.

2- Page Types

The number of pages is not the only key factor in trying to assess migration costs in advance. 

Instead, you have to assess the number of different page types (and therefore page designs) that need to be considered when evaluating the size of a migration (and thus the number of development days needed which will drive the costs).

Again this is an important element to be aware of - as it affects the project scope. 

Headless migrations typically involve senior development resources and there are lots of loose ends that need to be tied up. It is not a trivial exercise and thus it is important to budget accordingly. Ensuring that your web development agency has used the existing site to quote, is important so that there are strict conditions attached to any migration quotes you’ve received. 

3- Front End Design

Again a common misconception is that a CMS migration may include other elements like visual identity or user experience enhancements. 

A new front-end design is often not in scope with a standard migration. Hence the site will look, and largely behave the same. As mentioned earlier, the ideal situation is a design improvement to the front end including visual identity, user experience and navigation, messaging, etc being run in parallel with a back end migration.

Some layouts may also need to be adapted if existing content models were altered during the migration of data.

A great benefit of Headless is that it allows complete flexibility to update the front end design whenever your company requires. So if you’re the sort of company that has a brand refresh every couple of years this can be easily done without affecting the back end / content in the CMS. Headless also makes it easier to refresh the content structure, or top level navigation on a regular basis.

4- Developer Resource

When it comes to Headless,  it is 'a given' that the client will want a developer on board from the outset as that is the reality of a cutting edge Headless website.  You will want to work with people, real humans, who understand your business and your audience. And a headless solution allows them to do their job more effectively to serve the needs of the clients you are looking to attract.

Firstly, page types should be built with this in mind to allow for flexibility in new page layouts e.g. so new pages can be easily built by picking from multiple different blocks. Hence, The blocks and pages available should be discussed as part of the planning for the new site to ensure they can do most things they’re likely to need to do without needing further development.

Secondly, if there is no skilled in-house resource familiar with Jamstack / Headless CMS-backed websites you’ll end up with a situation where the marketing function will be unhappy that page building is no longer something they can manage in-house. This is a significant bug-bear and one that needs to be considered upfront. That said, not letting marketing have free reign to design new pages can also be a good thing as it helps ensure that specialist design input is used to create pages, helping to ensure great design, and better brand consistency.

5- Plugins

The average mature WordPress site (i.e. one that is a few years old) will have tens and tens of Plugins extending the core functionality of the CMS. In many instances most if not all of these will need to be replicated via API’s.

The Headless and API ecosystem is a rapidly growing area and you are likely to be able to find solutions comparable to most commonly used Wordpress plugins. Others are likely to require bespoke development and the cost of recreating these needs to be considered.

Most mature websites tend to function with lots of 3rd party apps and plugins in play. Migrating all of these is not a trivial exercise and finding like-for-like solutions should be part of the planning before deciding to undertake a migration to headless. 

6- The Teams

In most marketing teams, WordPress is a CMS that the team will be familiar with (although they’ll likely be keen to see the back of it). They’ll likely have encountered it on their career journey to-date. Despite its well documented issues, they will know where things are and how they work. 

Managing a Headless CMS-backed website is very different. You’ll potentially lose some core functionality and the fact that design elements are no longer accessible may be uncomfortable for some. 

When it comes to building new pages the approach will also be very different - and you’ll need access to a dedicated resource. The trade off is of course that a junior marketing team member will no longer be able to spin up pages (which in many instances is a good thing).

Hence, as mentioned above a marketing leader needs to be a part of the migration journey so that there are no downstream surprises. A headless CMS solution will be better tailored to their team's exact needs but like any major change there'll likely be some initial teething issues.

Finally, it should also be apparent from the above, that managing a migration in-house is not sensible, hence an agency will be needed to manage the process. And given the scale of tasks that need to be undertaken it is also important to ensure the quote is capped and you are not exposed to additional costs along the way.

7- Rebuild the Markup

Once you've rebuilt your markup/templates to be 'Headless', you are freed from the shackles of a specific CMS. The end result is a fully composable CMS/ extendable architecture where you can swap out specific parts later down the line (a headless-headless CMS migration is 100 times easier than a WordPress-headless one).

For any medium-sized site, it’s much simpler and more cost-effective in the long run to just start from scratch, even if you are replicating the design. It also allows you to get rid of any old CMS specific markup that is no longer required.

How Contento Helps Teams with Adoption?

When it comes to Contento we have focused on ensuring that usability was baked into our approach from Day 1:

  • Our UI is  straightforward and user friendly.

  • Our CMS is designed to require very little training to get the hang of it.

  • If done correctly a migration to Headless with flexible page types should mean an easier process to create new content and pages. 

  • Our inbuilt SEO functionality makes it easier to manage SEO

  • There are no “nasty plugins” to update with Headless


The early adopters of Headless CMS tend to be major brands who are attracted by omnichannel delivery, bespoke design, and faster page delivery.

Headless is likely to continue its explosive upward trajectory as the benefit set is compelling, especially for growing companies, which introduces the need to migrate. While this is not an insignificant task, this blog has served to highlight some of the areas to be aware of. 

However, the likelihood is once you’ve moved across you’ll never want to turn back!

Alan Gleeson - CMO Contento
Alan Gleeson

Co-Founder / CEO

Alan Gleeson has 15+ years extensive B2B SaaS experience working with several VC backed Startups & Scaleups in the UK, US & Ireland.

Recommended Reading

Group of people standing round a desk looking at a laptop

Working in marketing in B2B or SaaS is challenging at the best of times, but when it comes to managing a new website project it is never straightforward. After all, it can be a complex activity, with multiple actors and one that may only happen every 2-3 years.

Alan GleesonGrey Ellipse Icon

28 November 2022

Grey Ellipse Icon

8min read

Illustration of hand dragging boxes over into Contento screen on tablet

The following guide outlines the steps you need to take if you are considering migrating off WordPress to a Headless CMS like Contento.

Alan GleesonGrey Ellipse Icon

13 October 2022

Grey Ellipse Icon

7min read

image of three women working together, one at laptop and two looking at paperwork

The typical CMS upgrade path is from a traditional CMS like WordPress to a Headless CMS - in this short article, we explore what this entails and how you can prepare for it.

Alan GleesonGrey Ellipse Icon

3 October 2023

Grey Ellipse Icon

5min read

Newsletter Icon

Join our Newsletter

Learn how to build and manage a great website by subscribing to our newsletter to keep up to date with our products and services.

By subscribing to our newsletter you accept our GDPR terms and Privacy Policy