SftB #4 recap - How to migrate from WordPress to a headless CMS

As a part of the 4th edition of Stories from the Blok, Alba Silvente (Senior Frontend Consultant at Passionate People) and Christian Zoppi (DX Engineer at Storyblok) talked about migrating from WordPress to a headless CMS. This article is a short recap of the video presentation, which you can watch below.

Introduction: Monolithic vs headless

Alba started by giving a brief definition of headless and monolithic, and a quick comparison between the two approaches.

As with every other decision, the first thing to consider is the decision itself: When does it make sense to migrate to a headless system?

According to Alba, when you want to:

1. Choose your tech: Develop the frontend independently of the platform where the content is added.
2. Maintain brand consistency: Create a frontend that represents the company’s brand and unifies the look&feel of all products.
3. Create multiplatform projects: Without having to depend on different admin panels.
4. Make development easier: By having an isolated frontend, you can change the visual appearance without modifying the content structure.

Furthermore, there are some capabilities that a headless system can offer you, which you may not even be aware of. For example:

• It can take care of maintaining security and updates.
• It provides services to optimize assets and the speed of response with which they are served.
• Some (like Storyblok) also have a Visual Editor, which allows users to see a live preview of any content they may be working on.

Moving to a headless system

If you happen to believe that a headless solution fits your specific requirements and situation, then you can start your journey by following these steps:

1. Create and understand a Storyblok Space.
2. Create content types with the same schema as in your project, and add relationships.
3. Migrate your content to Storyblok (Using the Management API and configuring a script).

With the first two steps being rather self-explanatory, Christian took over to explain the third point in detail.

Migrating your content to Storyblok: How to create a migration script (Backend)

After evaluating your situation, you should have an idea if you need a script for migration or not. In case you think you need one, then you can get started!

You have to know what a migration script really does. In short:

• Retrieves data from the source CMS
• Transforms the data
• Sends the data to Storyblok

So let’s look at each step individually:

Retrieving data from the source CMS

The most important thing here is to figure out how we are going to retrieve the data. You probably have one of these options:

• Export functionality (this is the most likely option)
• API (pretty unlikely, since we are talking about migrating from a monolithic CMS)
• Database server (Always there, however can be a bit complicated or time consuming)

Transforming the data

After retrieving your data, there are a couple of things to take care of, before moving it to Storyblok. For example:

• Data mapping
• Fields with different schema (for example, links field)
• HTML/Plain text to Prose Mirror or Markdown
• Converting strings to arrays
• Replacing assets URLs
• New URLs structure

Sending the data to Storyblok

Here, you need to know 3 simple things:

1. Data structure of Storyblok
2. Management API
3. Limitations (requests per second, JSON max size, assets size)

Manual cleanup

After completing the 3 steps and sending your data to Storyblok, you should also do a manual cleanup. This simply means checking the final result of the import for:

• Formatting issues
• Image resolutions and ratios
• Special custom HTML elements in the content
• Special chars
• Iframes (even old Flash items) in imported HTML

That’s it! It is also helpful to go to Storyblok’s github organization and take a look at the WordPress importer package.

With the backend taken care of, Alba continued the presentation with everything you should take care of on your frontend.

Migrating your content to Storyblok: Frontend

There are also 3 main steps here that you should take care of:

• Creating a frontend project and connecting it to your Storyblok space
• Implementing the components and render the migrated content
• Deploy the project to Netlify and add build hooks

These steps are best explained through a video guide - so if you are interested, please go back to the top of the page and watch Alba explain everything in detail!