Tag: Headless

22 Jul

How To Migrate From WordPress To A Headless CMS

by TBSCategories: News

WordPress is the most used website builder in the world; almost half of the web has used WordPress to create their website. It makes sense, because it allows you to quickly create websites and has a rich plugin’s ecosystem to help you scale your site.

But technology is evolving, and there are more and more options that make it easier to create websites. Moreover, they give us the possibility to improve the website’s performance and to have more control and security over the application.

The initial WordPress architecture is monolithic, so the user interface and data access are combined on the same platform.

Since the introduction of the REST API on WordPress, it can be used in a headless way, allowing developers to use it as a backend and having the front-end in a different project.

In this decoupled way, models and controllers are bundled on the WordPress side, handling data manipulation and database interaction. Meanwhile, the front-end only interacts with the REST API via an HTTP client.

But this also has some disadvantages, you still need to configure and update WordPress, make it secure and are dependent on their technology for the development of new functionalities.

Related Reading on SmashingMag

For those of you who are just starting in the headless world, these articles will help you understand the ins and outs behind it and why everyone is starting to migrate.

But Why Migrate To A Headless CMS?

Taking into account that this article will showcase how to migrate from WordPress to a Headless CMS, WordPress is probably your current setup.

A Headless CMS will give us the freedom to focus only on the front-end project, being able to choose the technology we are familiar with, and on the structure of our data. In the end, it takes care of the content management and the content delivery, so that we can take care of the rendering part.

“A Headless CMS is a system that provides the same features as a Content Management System (CMS) and more, all exposed through an API.”

This type of setup is especially useful for companies that have multiple sites and want to reduce costs or simplify processes. A headless architecture allows these companies to centralize content management in a single administration interface, providing the APIs that will be consumed by the company’s different web pages.

Another common use of a headless architecture is to create a front-end project that represents the company brand. In this way, all the products that the company launches will have the same look and feel, but each one will have its own content, managed in the same administration panel.

Note: This example can be easily seen on conference websites such as JSWorld Conference and VueJS Amsterdam which, being from the same creators, the front-end project is the same, only the content changes.

Different to a CMS like WordPress, in a Headless CMS you have an administration panel already configured and maintained, and sometimes also hosted, for you. To start creating content, you just need to create an account, log in, and you will be able to create, edit, duplicate and delete your content, manage users, translate content and work with publication workflows, among other things.

A headless CMS will make it easier for the people in your team to understand the workflow, whether they are content creators or marketers, something to keep in mind if you aren’t the only one who will edit the content.

It is worth noting that some Headless CMS, not only focuses on offering you the services already offered by a CMS like WordPress. It also provides services such as image CDNs to resize or reformat your images on the fly, or additional security through S3 backups.

Having this setup will not only give you freedom, security and comfort, but will also improve the performance of your application without third-party services. Just by connecting your front-end project via an HTTP client and getting the components and data, you will be up and running.

The Benefits Of Going Headless And When It Makes Sense

WordPress’ architecture often does not offer the possibilities we sometimes need when working on a website, especially when it comes to optimizing performance, one of the most important points when ranking our site in a search engine like Google and especially now that Web Vitals is up and running.

But it is clear that if we have a personal site that only we ourselves work on, then it’s not necessary to migrate it to a headless setup. However, if more people are involved in that project (not just developers but content creators or marketing teams), then we should consider adopting Headless CMS.

How Can A Headless CMS Help Us Improve The Performance Of Our Website And The Quality Of Our Front-End Project?

  • By allowing you to develop the front-end in a way that is completely independent of the platform where you edit your content.

    The technology you choose is your own choice, if you wanted to upgrade your project to the latest front-end framework, you would not be dependent on a back-end and could do so without having to rethink migrations.

  • Allowing you to create multiplatform projects without having to depend on different administration panels.

    In the end, if for an app you need a shorter description than the main website, you can always make use of a new “short_description” field and just represent it on the front-end of that specific app.

  • It is intended to make development easier and simplify the process of creating a site, as well as scaling it.

    By having the front-end completely isolated we can change the visual appearance of our entire application without modifying the structure of our content.

  • Always offering services that will allow us to optimize our assets and the speed of response with which they are served to us. Ultimately all our data will be delivered through CDN networks.

A content delivery network (CDN), is a geographically distributed network of proxy servers and their data centers. The goal is to provide high availability and performance by distributing the service spatially relative to end-users.

What If We Are Concerned About How It Will Work With Our Brand’s Or Company’s Structure?

  • As well as supporting cross-platform applications, it also allows us to maintain brand consistency.

    Having the front-end as a base project and having multiples spaces in a Headless CMS, allows you to have consistency between your products and makes the scalability easier because we have less code to maintain.

  • Although not all headless CMS have this benefit, the headless CMS we are migrating to, Storyblok, has a Visual Editor, which allows creating independence among teams. The editors or content creators can access the panel to edit existing content or create new content, being able to see a preview of how it will look before publishing. So they won’t have to involve the development team in this process and can do their work more efficiently.
  • It also streamlines content management by allowing you to set up your own content workflow. You can define the stages that a piece of content must go through before being published and, only when it passes the process successfully, it will be published.

How Can A Headless CMS Save Time Compared To A Traditional CMS?

  • Taking care of maintaining the security of the platform and updating it on your behalf. Whenever there is a bug or users require a new feature, the team behind your Headless CMS will develop it for you, you just have to start using it!
  • Constantly improving the user experience (UX) and design (UI) for you, so that content creators and developers feel comfortable creating new fields, components or pages. But not only on the visual aspect, but they will also be looking to improve the performance of the database, so you get your content instantly and forget about all the work that is involved.
Monolithic vs Headless
Feature Monolithic Headless
Architecture Coupled: linked back-end front-end Decoupled: independent front-end project
Technology You will have to use the one in which the project is developed Freedom to choose your front-end technology
Cross-platform Limited to one front-end at a time Connects to any front-end projects
Content workflow Restrictive Custom
Security and updates You take care It takes care for you

Having seen the advantages that a headless setup can bring to our project and the people who work on it, I think it is time to look at the steps we need to migrate our project.

What You Need To Keep In Mind When Going Headless

As we have already mentioned, Headless CMS allow for a clean separation of concerns between content creators and developers. In this way (in a Headless CMS), the developer focuses on creating the content structure, which will be represented in the front-end project, and the editor will be in charge of using the components and filling them with content in the admin panel.

Type Of Content We Can Create In A Headless CMS

1. Types of entry or template

Similar to Custom Post Types in WordPress but with more freedom and extensibility when it comes to data types and editors.

When you go to create a new content entry in your dashboard, you expect to be able to choose what type it depends on the situation. For example, if you have a website with a blog you will want to have several types of templates, one for pages with listings or dynamic content called “page” and one for each blog entry “post“.

Depending on the headless CMS you have chosen, the name will vary but the concept is the same. In Storyblok these types of entities are called Content Type. “Content Types” define the type of content entry and can hold the basic fields for your content entries. By default, we have a “Page” content type.

2. Reusable components

In a Headless CMS, you can create, in addition to Content Types, nested components and reuse them between content types and other components. In Storyblok, this type of component — as you may have noticed from its name — is called Blok.

To use them in a Content Type such as a page, you will need to create a field in the schema of type blocks. This field allows you to add nested components to your page while adding content.

But, in principle, we will not need such components during the migration. It simply gives you the flexibility to create robust and dynamic applications without having to involve the developer.

For example, when a member of the marketing team wants to add a new Hero to the About us page, if the Hero component was created as nested and the page had a Blocks field, the marketing person could add the Hero without having to involve the developer.

Rendering The Data Coming From The Headless CMS

As we are defining the structure of our content in the Headless CMS panel, we have to consider which framework we want to create our front-end project with and which HTTP client we will use.

When choosing a framework we have to take several factors into account:

Are my team and I am familiar with this technology?

Does it allow me to render my content in the type of rendering my project needs?

Does it have plugins or modules that facilitate integration with the Headless CMS I’m using?

In most cases, a static site will be sufficient and will always be the most economical and high-performance answer. So, you just have to look for a static site generator for the technology you are familiar with, for example, Nuxt for Vue or Next for the React library.

Connecting these two things, a Headless CMS and a static site builder are considered as a set of web development best practices focused on providing the highest performance, security and lowest cost. This architecture is also known as Jamstack. It’s an architecture designed to make the web faster, more secure and easier to scale. It builds on many of the tools and workflows which developers love, and which bring maximum productivity.

By making use of the trendy frameworks, you will be assured of an integration guide with the Headless CMS you are going to work with, and most of them have already a module or package that allows you to obtain information from the API and in many cases extend it.

The only thing left for you to do is to define the structure of your components concerning how you have structured the data in your Headless CMS and automate the content publishing process. For example, using the Webhooks that the Headless CMS provides you with, you will be able to start a build process in your favourite hosting by its build hooks once the content has been published.

Amount Of Time You’ll Need

As with any migration, the time required will always depend proportionally on the complexity of your project. If we are talking about a common WordPress site you will only need to migrate the Post types that you have defined or that comes by default in it, such as Pages, Posts and Categories, and their content.

If, on the other hand, you have customized your project with multiple plugins, you will have to develop them through the front-end project or using the ones provided by your Headless CMS. For example, if we are SEO conscious and therefore make use of Yoast SEO on WordPress, we will have the Field-Type SEO plugin in Storyblok to help us in the transition, but we will still have to develop our sitemap in the front-end with a guide to help us.

In the end, all the burden of development will fall on the front-end project, as setting up the Headless CMS will not take that much time.

But let’s stop talking and let’s take a look at it!

Steps To Migrate Our Content From WordPress To Storyblok

The migration will consist of four steps, from the creation of a space in our new Headless CMS Storyblok to the representation of the migrated content in our front-end project, which we will see in detail below and in which I will leave you resources to make the migration easier for you.

Let’s get started!

1. Creating A Space In Storyblok

In order to create a space in Storyblok, you first need to have an account. To do this, you will need to select the plan that suits you best.

Go to the Pricing page and start with the plan that best suits your needs or try the free plan for testing.

Create your account, and you will be able to access the panel.

Choose ‘Create a new space’ and let’s get started!

Space is a content repository. Think of it as a place to keep all the content related to one project. Each space has its own components, data sources, assets, environments, domains, collaborators and permissions.

Take some time to explore the sections on the left sidebar. Start by browsing the following:

  • Content, this will be the folder where the content will be stored, where the marketing team will spend most of their time.
  • Assets, where all the images will be stored, which you can then get through the CDN service, optimized and of any size.
  • Components, where you will create the Content types and Nested components.
  • Settings, the section where you will be able to configure the data of your space as well as the languages of your application, the workflows you want your content to follow before being published, user permissions, etc. Let’s say that this area will be the one related to the IT team of the project.

If you still want to explore every option on the dashboard before diving into the migration, I recommend taking a look at Understanding the UI by Storyblok.

Now that you know a bit about the Storyblok ecosystem, it’s time to define what the content of our application will look like.

2. Defining Models

To migrate WordPress content to Storyblok, the next step is to create the schemas that define the WP data structure by creating Post Types in the Storyblok space.

Let’s start with pages and posts (the main Post Types in any WP site), which we’ll call page and post in Storyblok.

The schema of pages in WP contains the fields: title, slug, featured image, date, and content.

Note: To see all the fields contained in a Post Type go to the schema at WP REST API schema references.

What you need to know is that, by default, any Content Type in Storyblok will have some fields already defined for you, such as Name, Slug, Tags, First published date, and so on.

Those fields could be used to migrate the content from WP. You will only need to extend it by adding featured_image and content in the Page Content Type.

Go to the Components section in your space, click on the page created by default, remove the body field and add featured_image as type Assets > Images and content as Rich-text.

Once the page schema is ready, let’s move on to the post. For the Post Content Type, it is necessary to include more information, such as featured_image, excerpt, content, and relationships to other types such as Authors or Categories.

Since Authors and Categories will also have their own content, go to the Content section in the sidebar and create a couple of folders called authors and categories.

Each of the folders must have a default Content Type associated. To do this, in the Components section, create Author and Category as new Content Types, and then associate the Content Type relative to each folder by clicking on the three dots on the right of the folder and selecting Settings.

In this way, in the Post Content Type you can add a Single-Option or Multi-Options field with source Stories and point to the folder created for each field:

  • Authors
    This specifies the folder where they are located authors/.
  • Categories
    This specifies the folder where they are located categories/.

Note: If you want to know more about this relationship, have a look at the article Authors and Articles Relationship.

Now that you have seen how to create a couple of Content Types and how to create relationships between them, you will have to define the rest of the models following the same steps.

Adding A Content Type: Global

And you ask yourself, what about the content that all my pages will share? Like the navigation menu, footer, and other common elements?

Don’t worry, Storyblok has already thought about that and offers us a simple guide to define our global elements dynamically. It shows us how to create a global Content Type and how to use it in the Content section.

3. Migrating The Content

Now it’s time to start migrating the content you have stored. To access WP content you need to access the REST JSON API. Access the path /wp-json, if the project is deployed, or ?rest_route=/ if local.

In case neither of the two routes works, inspect the HTML of your page for a link in the head with rel="https://api.w.org/", as indicated in the WP discovery guide, and get the correct one.

To help us during the migration, the Storyblok developers have provided us with a plugin that will save us a lot of work. This plugin is called wordpress-importer, on it, it is possible to define the equivalent Content Type in Storyblok for the WP Post type to be migrated, and it will push it to our space and migrate the images to our Assets section for us.

Note: Using this script requires node ≥14.0.0 because it’s using optional chaining.

Creating The Migration Script

The first thing to do is to clone the repository. Then, install the NPM packages, using npm install or yarn, and create a file in the root of the project as migrateWPtoStoryblok.js. In order to run the script you need a script in package.json to run it, add:

"migrate": "node ./migrateWPtoStoryblok.js"

Once everything is ready, it’s time to start defining the script following the README specifications. And, as you can see, the next thing that will be needed is to find the Space_id and the OAuth token to connect to the Storyblok space.

  • The Space_id is in the Settings section of the sidebar, as soon as you click on it, you will see it on the right side.
  • To generate the OAuth token, you need to go to the top of the sidebar, click on the little arrow right next to the Storyblok logo, and go to My Account. If we scroll down we will see the Personal access tokens section, generate one, and copy it.

When you have obtained both secrets, you can add them to the beginning of the script along with the URL of the JSON API of your project:

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   token: 'storyblok-oauth-token', // My Account > Personal access tokens   space_id: 'space-id', // Settings })

As described in previous sections, the Page Content Type in Storyblok is the equivalent of the Post Type in WP pages. In the code block below, you’ll see where you’ll need to specify each.

And, once the Post Type and Content Type are defined, it is time to specify the name of the fields used in this entity type in WP and the equivalent name in Storyblok, in the schema_mapping option.

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   // ... Secrets   content_types: [     {       name: 'pages', // Post type in WP       new_content_type: 'page', // Equivalent Content type in Storyblok       folder: '', // OPTIONAL: To save all the content of the same type in a specific folder       schema_mapping: {         "title": "name", // "Field in WP": "Field in Storyblok"       }     }   ] })

Note: For the migration to work correctly, make sure that the permalinks are selected by the name of the entry and not as simple. Otherwise, the script will not create the parent-child relationship between pages.

Within the schema_mapping you can define several types of fields, these can be:

  • A simple field, such as title.
  • A sub-property of a field, like in this case the URL of the feature image.
    Note: The plugin itself takes care of migrating the images to the Storyblok space via the associated URL in links.wp:featuredmedia.0.

  • A field migrated to a nested block in Storyblok.

    Imagine you want to create a component in Storyblok to define your site’s rich text so that all post types using it have the same style and options.

    For that, you can use the object format and specify the name of the field in the Storyblok model under the field property, the name of the component you want to store inside that field, and the name of the field inside the component where the content will be migrated.

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   // ... Secrets   content_types: [     {       // ... Post type WP:Storyblok       schema_mapping: {         "title": "name", // "Field in WP": "Field in Storyblok"         "_links.wp:featuredmedia.0": "content.preview_image", // Using the dot notation you can define subproperties.         // Using nested blocks in Storyblok         "content": {           field: 'content.body_items', // Field name in Storyblok           component: "rich-text", // Component name inside the above field           component_field: "content" // Field name inside the component where you want to migrate the content         }       }     }   ] })  wp2storyblok.migrate()

Entry Type Page

Now that you know how to define the field types, for the page schema, it would look like in the code block below.

The plugin will take care of the parent-child relationship between pages by creating a folder in Storyblok under the parent’s slug and associating the parent as the home of that folder.

Furthermore, if the content field contains images, the plugin will also migrate it for you!

{   name: 'pages', // Name of the post type in WP   new_content_type: 'page', // Name of the Content Type in Storyblok   schema_mapping: {     "date": "first_published_at",     "title": "name",     "slug": "slug",     "_links.wp:featuredmedia.0": "content.featured_image",     "content": "content.content",   } }

Entry Type Post

Posts have a schema similar to pages but, in this case, to store them in a folder you must define the name of the folder below the entry type:

{   name: 'posts', // Post type name in WP   new_content_type: 'post', // Content Type name in Storyblok   folder: 'articles', // Destination folder name in Storyblok   schema_mapping: {     "date": "first_published_at",     "title": "name",     "slug": "slug",     "_links.wp:featuredmedia.0": "content.featured_image",     "excerpt": "content.excerpt",     "content": "content.content",   } }
Entry Type Category

And once the schema for posts has been defined, it makes sense to define the schema for the categories so that they can be associated as described in the previous section.

In order to define the folder that contains them as categories and not as category, their default name, you must go to the Permalinks option in the WordPress admin and change the Categories base option to categories. Then the multi-option field of the Post entries will be the one that has the relationship with the corresponding categories.

Note: These steps are the same as those to be followed for migrating authors and linking them to articles.

{   name: 'categories', // Name of the post type in WP   new_content_type: 'category', // Name of the Content Type in Storyblok   // By default will be contained by a folder called Category (change it in the Permalinks option in WP)   schema_mapping: {     "name": "name",     "slug": "slug",     "description": "content.description",     "parent": "content.parent",   } }

Full Final Script

The code below will be the resulting migration script from a WP project with the basic types to the Storyblok space we had created.

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   token: '',   space_id: 34234,   content_types: [     {       name: 'pages', // Name of the post type in WP       new_content_type: 'page', // Name of the Content Type in Storyblok       schema_mapping: {         "date": "first_published_at",         "title": "name",         "slug": "slug",         "_links.wp:featuredmedia.0": "content.featured_image",         "content": "content.content",       }     },     {       name: 'categories', // Name of the post type in WP       new_content_type: 'category', // Name of the Content Type in Storyblok       // By default will be contained by a folder called Category (change it in the Permalinks option in WP)       schema_mapping: {         "name": "name",         "slug": "slug",         "description": "content.description",         "parent": "content.parent",       }     },     // Add authors as categories.     {       name: 'posts', // Name of the post type in WP       new_content_type: 'post', // Name of the Content Type in Storyblok       folder: 'articles', // Name of the destination folder in Storyblok       schema_mapping: {         "date": "first_published_at",         "title": "name",         "slug": "slug",         "_links.wp:featuredmedia.0": "content.featured_image",         "excerpt": "content.excerpt",         "content": "content.content",       }     }     // More schemas...   ] })  wp2storyblok.migrate()

4. Create A Front-End Project

Now that the content is already stored in the Storyblok dashboard, it’s time to connect the Front-end project to Storyblok.

Whatever your framework or JS library, Storyblok provides the JavaScript client that will help you with the integration. In addition, in case you are using a specific framework, you will find other packages that will ease the way, like in Nuxt the storyblok-nuxt module.

This JavaScript API will also include a bridge between Storyblok and your Front-end application. The bridge is responsible for communicating via iframe with Storyblok to tell the editing interface which component to open when the user clicks on it.

Here is a list of tutorials you can find on Storyblok to connect your Front-end project.

Note: If you don’t find your technology among them, don’t worry there are many other tutorials on the Storyblok website, search for yours in the search engine, and if you don’t find one I encourage you to contact them, and you will help many more people!

5. Host Your Front-End Project And Automate Deploy

Once your project is ready to go into production, you choose a hosting provider and link your repository for easy deployment, then you ask yourself:

How do I redeploy my static site if I publish an entry on Storyblok?

The answer is very simple: by using the webhooks offered by Storyblok and the build hooks of your hosting.

To give you a real example, you can create build hooks URLs in Netlify within the deployment section; the URL created for Storyblok in the build hooks will go in the Settings → Webhooks → Story published & unpublished field in the Storyblok space.

Guides And Tools We Have Used During Migration

Let’s recap the links that have helped in the migration of the content and those that helped to understand the functioning of the REST API and the headless CMS to which you are migrating.

WP REST API Documentation Needed

REST API
Schemas

Migrating To Storyblok

General Info
Documentation
Global Components
SEO Related
Webhooks And Build Hooks
Scripts And Packages

Jamstack

Conclusion

After reading this article you will have what you need to understand why a headless setup will improve your project, how to migrate from your WordPress project to a headless CMS like Storyblok and how to keep improving and extending your project.

As you have seen, the possibilities of a headless setup are endless. After the migration, you will have enormous flexibility to scale your project, improve its performance and SEO, increase the productivity of the development team and stay on top of the latest trends.

Everyone is starting to migrate and there is more and more content and scripts that make it easier. What are you waiting for to migrate your WordPress?

Articles on Smashing Magazine — For Web Designers And Developers

22 Jul

How To Migrate From WordPress To A Headless CMS

by TBSCategories: News

WordPress is the most used website builder in the world; almost half of the web has used WordPress to create their website. It makes sense, because it allows you to quickly create websites and has a rich plugin’s ecosystem to help you scale your site.

But technology is evolving, and there are more and more options that make it easier to create websites. Moreover, they give us the possibility to improve the website’s performance and to have more control and security over the application.

The initial WordPress architecture is monolithic, so the user interface and data access are combined on the same platform.

Since the introduction of the REST API on WordPress, it can be used in a headless way, allowing developers to use it as a backend and having the front-end in a different project.

In this decoupled way, models and controllers are bundled on the WordPress side, handling data manipulation and database interaction. Meanwhile, the front-end only interacts with the REST API via an HTTP client.

But this also has some disadvantages, you still need to configure and update WordPress, make it secure and are dependent on their technology for the development of new functionalities.

Related Reading on SmashingMag

For those of you who are just starting in the headless world, these articles will help you understand the ins and outs behind it and why everyone is starting to migrate.

But Why Migrate To A Headless CMS?

Taking into account that this article will showcase how to migrate from WordPress to a Headless CMS, WordPress is probably your current setup.

A Headless CMS will give us the freedom to focus only on the front-end project, being able to choose the technology we are familiar with, and on the structure of our data. In the end, it takes care of the content management and the content delivery, so that we can take care of the rendering part.

“A Headless CMS is a system that provides the same features as a Content Management System (CMS) and more, all exposed through an API.”

This type of setup is especially useful for companies that have multiple sites and want to reduce costs or simplify processes. A headless architecture allows these companies to centralize content management in a single administration interface, providing the APIs that will be consumed by the company’s different web pages.

Another common use of a headless architecture is to create a front-end project that represents the company brand. In this way, all the products that the company launches will have the same look and feel, but each one will have its own content, managed in the same administration panel.

Note: This example can be easily seen on conference websites such as JSWorld Conference and VueJS Amsterdam which, being from the same creators, the front-end project is the same, only the content changes.

Different to a CMS like WordPress, in a Headless CMS you have an administration panel already configured and maintained, and sometimes also hosted, for you. To start creating content, you just need to create an account, log in, and you will be able to create, edit, duplicate and delete your content, manage users, translate content and work with publication workflows, among other things.

A headless CMS will make it easier for the people in your team to understand the workflow, whether they are content creators or marketers, something to keep in mind if you aren’t the only one who will edit the content.

It is worth noting that some Headless CMS, not only focuses on offering you the services already offered by a CMS like WordPress. It also provides services such as image CDNs to resize or reformat your images on the fly, or additional security through S3 backups.

Having this setup will not only give you freedom, security and comfort, but will also improve the performance of your application without third-party services. Just by connecting your front-end project via an HTTP client and getting the components and data, you will be up and running.

The Benefits Of Going Headless And When It Makes Sense

WordPress’ architecture often does not offer the possibilities we sometimes need when working on a website, especially when it comes to optimizing performance, one of the most important points when ranking our site in a search engine like Google and especially now that Web Vitals is up and running.

But it is clear that if we have a personal site that only we ourselves work on, then it’s not necessary to migrate it to a headless setup. However, if more people are involved in that project (not just developers but content creators or marketing teams), then we should consider adopting Headless CMS.

How Can A Headless CMS Help Us Improve The Performance Of Our Website And The Quality Of Our Front-End Project?

  • By allowing you to develop the front-end in a way that is completely independent of the platform where you edit your content.

    The technology you choose is your own choice, if you wanted to upgrade your project to the latest front-end framework, you would not be dependent on a back-end and could do so without having to rethink migrations.

  • Allowing you to create multiplatform projects without having to depend on different administration panels.

    In the end, if for an app you need a shorter description than the main website, you can always make use of a new “short_description” field and just represent it on the front-end of that specific app.

  • It is intended to make development easier and simplify the process of creating a site, as well as scaling it.

    By having the front-end completely isolated we can change the visual appearance of our entire application without modifying the structure of our content.

  • Always offering services that will allow us to optimize our assets and the speed of response with which they are served to us. Ultimately all our data will be delivered through CDN networks.

A content delivery network (CDN), is a geographically distributed network of proxy servers and their data centers. The goal is to provide high availability and performance by distributing the service spatially relative to end-users.

What If We Are Concerned About How It Will Work With Our Brand’s Or Company’s Structure?

  • As well as supporting cross-platform applications, it also allows us to maintain brand consistency.

    Having the front-end as a base project and having multiples spaces in a Headless CMS, allows you to have consistency between your products and makes the scalability easier because we have less code to maintain.

  • Although not all headless CMS have this benefit, the headless CMS we are migrating to, Storyblok, has a Visual Editor, which allows creating independence among teams. The editors or content creators can access the panel to edit existing content or create new content, being able to see a preview of how it will look before publishing. So they won’t have to involve the development team in this process and can do their work more efficiently.
  • It also streamlines content management by allowing you to set up your own content workflow. You can define the stages that a piece of content must go through before being published and, only when it passes the process successfully, it will be published.

How Can A Headless CMS Save Time Compared To A Traditional CMS?

  • Taking care of maintaining the security of the platform and updating it on your behalf. Whenever there is a bug or users require a new feature, the team behind your Headless CMS will develop it for you, you just have to start using it!
  • Constantly improving the user experience (UX) and design (UI) for you, so that content creators and developers feel comfortable creating new fields, components or pages. But not only on the visual aspect, but they will also be looking to improve the performance of the database, so you get your content instantly and forget about all the work that is involved.
Monolithic vs Headless
Feature Monolithic Headless
Architecture Coupled: linked back-end front-end Decoupled: independent front-end project
Technology You will have to use the one in which the project is developed Freedom to choose your front-end technology
Cross-platform Limited to one front-end at a time Connects to any front-end projects
Content workflow Restrictive Custom
Security and updates You take care It takes care for you

Having seen the advantages that a headless setup can bring to our project and the people who work on it, I think it is time to look at the steps we need to migrate our project.

What You Need To Keep In Mind When Going Headless

As we have already mentioned, Headless CMS allow for a clean separation of concerns between content creators and developers. In this way (in a Headless CMS), the developer focuses on creating the content structure, which will be represented in the front-end project, and the editor will be in charge of using the components and filling them with content in the admin panel.

Type Of Content We Can Create In A Headless CMS

1. Types of entry or template

Similar to Custom Post Types in WordPress but with more freedom and extensibility when it comes to data types and editors.

When you go to create a new content entry in your dashboard, you expect to be able to choose what type it depends on the situation. For example, if you have a website with a blog you will want to have several types of templates, one for pages with listings or dynamic content called “page” and one for each blog entry “post“.

Depending on the headless CMS you have chosen, the name will vary but the concept is the same. In Storyblok these types of entities are called Content Type. “Content Types” define the type of content entry and can hold the basic fields for your content entries. By default, we have a “Page” content type.

2. Reusable components

In a Headless CMS, you can create, in addition to Content Types, nested components and reuse them between content types and other components. In Storyblok, this type of component — as you may have noticed from its name — is called Blok.

To use them in a Content Type such as a page, you will need to create a field in the schema of type blocks. This field allows you to add nested components to your page while adding content.

But, in principle, we will not need such components during the migration. It simply gives you the flexibility to create robust and dynamic applications without having to involve the developer.

For example, when a member of the marketing team wants to add a new Hero to the About us page, if the Hero component was created as nested and the page had a Blocks field, the marketing person could add the Hero without having to involve the developer.

Rendering The Data Coming From The Headless CMS

As we are defining the structure of our content in the Headless CMS panel, we have to consider which framework we want to create our front-end project with and which HTTP client we will use.

When choosing a framework we have to take several factors into account:

Are my team and I am familiar with this technology?

Does it allow me to render my content in the type of rendering my project needs?

Does it have plugins or modules that facilitate integration with the Headless CMS I’m using?

In most cases, a static site will be sufficient and will always be the most economical and high-performance answer. So, you just have to look for a static site generator for the technology you are familiar with, for example, Nuxt for Vue or Next for the React library.

Connecting these two things, a Headless CMS and a static site builder are considered as a set of web development best practices focused on providing the highest performance, security and lowest cost. This architecture is also known as Jamstack. It’s an architecture designed to make the web faster, more secure and easier to scale. It builds on many of the tools and workflows which developers love, and which bring maximum productivity.

By making use of the trendy frameworks, you will be assured of an integration guide with the Headless CMS you are going to work with, and most of them have already a module or package that allows you to obtain information from the API and in many cases extend it.

The only thing left for you to do is to define the structure of your components concerning how you have structured the data in your Headless CMS and automate the content publishing process. For example, using the Webhooks that the Headless CMS provides you with, you will be able to start a build process in your favourite hosting by its build hooks once the content has been published.

Amount Of Time You’ll Need

As with any migration, the time required will always depend proportionally on the complexity of your project. If we are talking about a common WordPress site you will only need to migrate the Post types that you have defined or that comes by default in it, such as Pages, Posts and Categories, and their content.

If, on the other hand, you have customized your project with multiple plugins, you will have to develop them through the front-end project or using the ones provided by your Headless CMS. For example, if we are SEO conscious and therefore make use of Yoast SEO on WordPress, we will have the Field-Type SEO plugin in Storyblok to help us in the transition, but we will still have to develop our sitemap in the front-end with a guide to help us.

In the end, all the burden of development will fall on the front-end project, as setting up the Headless CMS will not take that much time.

But let’s stop talking and let’s take a look at it!

Steps To Migrate Our Content From WordPress To Storyblok

The migration will consist of four steps, from the creation of a space in our new Headless CMS Storyblok to the representation of the migrated content in our front-end project, which we will see in detail below and in which I will leave you resources to make the migration easier for you.

Let’s get started!

1. Creating A Space In Storyblok

In order to create a space in Storyblok, you first need to have an account. To do this, you will need to select the plan that suits you best.

Go to the Pricing page and start with the plan that best suits your needs or try the free plan for testing.

Create your account, and you will be able to access the panel.

Choose ‘Create a new space’ and let’s get started!

Space is a content repository. Think of it as a place to keep all the content related to one project. Each space has its own components, data sources, assets, environments, domains, collaborators and permissions.

Take some time to explore the sections on the left sidebar. Start by browsing the following:

  • Content, this will be the folder where the content will be stored, where the marketing team will spend most of their time.
  • Assets, where all the images will be stored, which you can then get through the CDN service, optimized and of any size.
  • Components, where you will create the Content types and Nested components.
  • Settings, the section where you will be able to configure the data of your space as well as the languages of your application, the workflows you want your content to follow before being published, user permissions, etc. Let’s say that this area will be the one related to the IT team of the project.

If you still want to explore every option on the dashboard before diving into the migration, I recommend taking a look at Understanding the UI by Storyblok.

Now that you know a bit about the Storyblok ecosystem, it’s time to define what the content of our application will look like.

2. Defining Models

To migrate WordPress content to Storyblok, the next step is to create the schemas that define the WP data structure by creating Post Types in the Storyblok space.

Let’s start with pages and posts (the main Post Types in any WP site), which we’ll call page and post in Storyblok.

The schema of pages in WP contains the fields: title, slug, featured image, date, and content.

Note: To see all the fields contained in a Post Type go to the schema at WP REST API schema references.

What you need to know is that, by default, any Content Type in Storyblok will have some fields already defined for you, such as Name, Slug, Tags, First published date, and so on.

Those fields could be used to migrate the content from WP. You will only need to extend it by adding featured_image and content in the Page Content Type.

Go to the Components section in your space, click on the page created by default, remove the body field and add featured_image as type Assets > Images and content as Rich-text.

Once the page schema is ready, let’s move on to the post. For the Post Content Type, it is necessary to include more information, such as featured_image, excerpt, content, and relationships to other types such as Authors or Categories.

Since Authors and Categories will also have their own content, go to the Content section in the sidebar and create a couple of folders called authors and categories.

Each of the folders must have a default Content Type associated. To do this, in the Components section, create Author and Category as new Content Types, and then associate the Content Type relative to each folder by clicking on the three dots on the right of the folder and selecting Settings.

In this way, in the Post Content Type you can add a Single-Option or Multi-Options field with source Stories and point to the folder created for each field:

  • Authors
    This specifies the folder where they are located authors/.
  • Categories
    This specifies the folder where they are located categories/.

Note: If you want to know more about this relationship, have a look at the article Authors and Articles Relationship.

Now that you have seen how to create a couple of Content Types and how to create relationships between them, you will have to define the rest of the models following the same steps.

Adding A Content Type: Global

And you ask yourself, what about the content that all my pages will share? Like the navigation menu, footer, and other common elements?

Don’t worry, Storyblok has already thought about that and offers us a simple guide to define our global elements dynamically. It shows us how to create a global Content Type and how to use it in the Content section.

3. Migrating The Content

Now it’s time to start migrating the content you have stored. To access WP content you need to access the REST JSON API. Access the path /wp-json, if the project is deployed, or ?rest_route=/ if local.

In case neither of the two routes works, inspect the HTML of your page for a link in the head with rel="https://api.w.org/", as indicated in the WP discovery guide, and get the correct one.

To help us during the migration, the Storyblok developers have provided us with a plugin that will save us a lot of work. This plugin is called wordpress-importer, on it, it is possible to define the equivalent Content Type in Storyblok for the WP Post type to be migrated, and it will push it to our space and migrate the images to our Assets section for us.

Note: Using this script requires node ≥14.0.0 because it’s using optional chaining.

Creating The Migration Script

The first thing to do is to clone the repository. Then, install the NPM packages, using npm install or yarn, and create a file in the root of the project as migrateWPtoStoryblok.js. In order to run the script you need a script in package.json to run it, add:

"migrate": "node ./migrateWPtoStoryblok.js"

Once everything is ready, it’s time to start defining the script following the README specifications. And, as you can see, the next thing that will be needed is to find the Space_id and the OAuth token to connect to the Storyblok space.

  • The Space_id is in the Settings section of the sidebar, as soon as you click on it, you will see it on the right side.
  • To generate the OAuth token, you need to go to the top of the sidebar, click on the little arrow right next to the Storyblok logo, and go to My Account. If we scroll down we will see the Personal access tokens section, generate one, and copy it.

When you have obtained both secrets, you can add them to the beginning of the script along with the URL of the JSON API of your project:

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   token: 'storyblok-oauth-token', // My Account > Personal access tokens   space_id: 'space-id', // Settings })

As described in previous sections, the Page Content Type in Storyblok is the equivalent of the Post Type in WP pages. In the code block below, you’ll see where you’ll need to specify each.

And, once the Post Type and Content Type are defined, it is time to specify the name of the fields used in this entity type in WP and the equivalent name in Storyblok, in the schema_mapping option.

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   // ... Secrets   content_types: [     {       name: 'pages', // Post type in WP       new_content_type: 'page', // Equivalent Content type in Storyblok       folder: '', // OPTIONAL: To save all the content of the same type in a specific folder       schema_mapping: {         "title": "name", // "Field in WP": "Field in Storyblok"       }     }   ] })

Note: For the migration to work correctly, make sure that the permalinks are selected by the name of the entry and not as simple. Otherwise, the script will not create the parent-child relationship between pages.

Within the schema_mapping you can define several types of fields, these can be:

  • A simple field, such as title.
  • A sub-property of a field, like in this case the URL of the feature image.
    Note: The plugin itself takes care of migrating the images to the Storyblok space via the associated URL in links.wp:featuredmedia.0.

  • A field migrated to a nested block in Storyblok.

    Imagine you want to create a component in Storyblok to define your site’s rich text so that all post types using it have the same style and options.

    For that, you can use the object format and specify the name of the field in the Storyblok model under the field property, the name of the component you want to store inside that field, and the name of the field inside the component where the content will be migrated.

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   // ... Secrets   content_types: [     {       // ... Post type WP:Storyblok       schema_mapping: {         "title": "name", // "Field in WP": "Field in Storyblok"         "_links.wp:featuredmedia.0": "content.preview_image", // Using the dot notation you can define subproperties.         // Using nested blocks in Storyblok         "content": {           field: 'content.body_items', // Field name in Storyblok           component: "rich-text", // Component name inside the above field           component_field: "content" // Field name inside the component where you want to migrate the content         }       }     }   ] })  wp2storyblok.migrate()

Entry Type Page

Now that you know how to define the field types, for the page schema, it would look like in the code block below.

The plugin will take care of the parent-child relationship between pages by creating a folder in Storyblok under the parent’s slug and associating the parent as the home of that folder.

Furthermore, if the content field contains images, the plugin will also migrate it for you!

{   name: 'pages', // Name of the post type in WP   new_content_type: 'page', // Name of the Content Type in Storyblok   schema_mapping: {     "date": "first_published_at",     "title": "name",     "slug": "slug",     "_links.wp:featuredmedia.0": "content.featured_image",     "content": "content.content",   } }

Entry Type Post

Posts have a schema similar to pages but, in this case, to store them in a folder you must define the name of the folder below the entry type:

{   name: 'posts', // Post type name in WP   new_content_type: 'post', // Content Type name in Storyblok   folder: 'articles', // Destination folder name in Storyblok   schema_mapping: {     "date": "first_published_at",     "title": "name",     "slug": "slug",     "_links.wp:featuredmedia.0": "content.featured_image",     "excerpt": "content.excerpt",     "content": "content.content",   } }
Entry Type Category

And once the schema for posts has been defined, it makes sense to define the schema for the categories so that they can be associated as described in the previous section.

In order to define the folder that contains them as categories and not as category, their default name, you must go to the Permalinks option in the WordPress admin and change the Categories base option to categories. Then the multi-option field of the Post entries will be the one that has the relationship with the corresponding categories.

Note: These steps are the same as those to be followed for migrating authors and linking them to articles.

{   name: 'categories', // Name of the post type in WP   new_content_type: 'category', // Name of the Content Type in Storyblok   // By default will be contained by a folder called Category (change it in the Permalinks option in WP)   schema_mapping: {     "name": "name",     "slug": "slug",     "description": "content.description",     "parent": "content.parent",   } }

Full Final Script

The code below will be the resulting migration script from a WP project with the basic types to the Storyblok space we had created.

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   token: '',   space_id: 34234,   content_types: [     {       name: 'pages', // Name of the post type in WP       new_content_type: 'page', // Name of the Content Type in Storyblok       schema_mapping: {         "date": "first_published_at",         "title": "name",         "slug": "slug",         "_links.wp:featuredmedia.0": "content.featured_image",         "content": "content.content",       }     },     {       name: 'categories', // Name of the post type in WP       new_content_type: 'category', // Name of the Content Type in Storyblok       // By default will be contained by a folder called Category (change it in the Permalinks option in WP)       schema_mapping: {         "name": "name",         "slug": "slug",         "description": "content.description",         "parent": "content.parent",       }     },     // Add authors as categories.     {       name: 'posts', // Name of the post type in WP       new_content_type: 'post', // Name of the Content Type in Storyblok       folder: 'articles', // Name of the destination folder in Storyblok       schema_mapping: {         "date": "first_published_at",         "title": "name",         "slug": "slug",         "_links.wp:featuredmedia.0": "content.featured_image",         "excerpt": "content.excerpt",         "content": "content.content",       }     }     // More schemas...   ] })  wp2storyblok.migrate()

4. Create A Front-End Project

Now that the content is already stored in the Storyblok dashboard, it’s time to connect the Front-end project to Storyblok.

Whatever your framework or JS library, Storyblok provides the JavaScript client that will help you with the integration. In addition, in case you are using a specific framework, you will find other packages that will ease the way, like in Nuxt the storyblok-nuxt module.

This JavaScript API will also include a bridge between Storyblok and your Front-end application. The bridge is responsible for communicating via iframe with Storyblok to tell the editing interface which component to open when the user clicks on it.

Here is a list of tutorials you can find on Storyblok to connect your Front-end project.

Note: If you don’t find your technology among them, don’t worry there are many other tutorials on the Storyblok website, search for yours in the search engine, and if you don’t find one I encourage you to contact them, and you will help many more people!

5. Host Your Front-End Project And Automate Deploy

Once your project is ready to go into production, you choose a hosting provider and link your repository for easy deployment, then you ask yourself:

How do I redeploy my static site if I publish an entry on Storyblok?

The answer is very simple: by using the webhooks offered by Storyblok and the build hooks of your hosting.

To give you a real example, you can create build hooks URLs in Netlify within the deployment section; the URL created for Storyblok in the build hooks will go in the Settings → Webhooks → Story published & unpublished field in the Storyblok space.

Guides And Tools We Have Used During Migration

Let’s recap the links that have helped in the migration of the content and those that helped to understand the functioning of the REST API and the headless CMS to which you are migrating.

WP REST API Documentation Needed

REST API
Schemas

Migrating To Storyblok

General Info
Documentation
Global Components
SEO Related
Webhooks And Build Hooks
Scripts And Packages

Jamstack

Conclusion

After reading this article you will have what you need to understand why a headless setup will improve your project, how to migrate from your WordPress project to a headless CMS like Storyblok and how to keep improving and extending your project.

As you have seen, the possibilities of a headless setup are endless. After the migration, you will have enormous flexibility to scale your project, improve its performance and SEO, increase the productivity of the development team and stay on top of the latest trends.

Everyone is starting to migrate and there is more and more content and scripts that make it easier. What are you waiting for to migrate your WordPress?

Articles on Smashing Magazine — For Web Designers And Developers

21 Jul

How To Migrate From WordPress To A Headless CMS

by TBSCategories: News

WordPress is the most used website builder in the world; almost half of the web has used WordPress to create their website. It makes sense, because it allows you to quickly create websites and has a rich plugin’s ecosystem to help you scale your site.

But technology is evolving, and there are more and more options that make it easier to create websites. Moreover, they give us the possibility to improve the website’s performance and to have more control and security over the application.

The initial WordPress architecture is monolithic, so the user interface and data access are combined on the same platform.

Since the introduction of the REST API on WordPress, it can be used in a headless way, allowing developers to use it as a backend and having the front-end in a different project.

In this decoupled way, models and controllers are bundled on the WordPress side, handling data manipulation and database interaction. Meanwhile, the front-end only interacts with the REST API via an HTTP client.

But this also has some disadvantages, you still need to configure and update WordPress, make it secure and are dependent on their technology for the development of new functionalities.

Related Reading on SmashingMag

For those of you who are just starting in the headless world, these articles will help you understand the ins and outs behind it and why everyone is starting to migrate.

But Why Migrate To A Headless CMS?

Taking into account that this article will showcase how to migrate from WordPress to a Headless CMS, WordPress is probably your current setup.

A Headless CMS will give us the freedom to focus only on the front-end project, being able to choose the technology we are familiar with, and on the structure of our data. In the end, it takes care of the content management and the content delivery, so that we can take care of the rendering part.

“A Headless CMS is a system that provides the same features as a Content Management System (CMS) and more, all exposed through an API.”

This type of setup is especially useful for companies that have multiple sites and want to reduce costs or simplify processes. A headless architecture allows these companies to centralize content management in a single administration interface, providing the APIs that will be consumed by the company’s different web pages.

Another common use of a headless architecture is to create a front-end project that represents the company brand. In this way, all the products that the company launches will have the same look and feel, but each one will have its own content, managed in the same administration panel.

Note: This example can be easily seen on conference websites such as JSWorld Conference and VueJS Amsterdam which, being from the same creators, the front-end project is the same, only the content changes.

Different to a CMS like WordPress, in a Headless CMS you have an administration panel already configured and maintained, and sometimes also hosted, for you. To start creating content, you just need to create an account, log in, and you will be able to create, edit, duplicate and delete your content, manage users, translate content and work with publication workflows, among other things.

A headless CMS will make it easier for the people in your team to understand the workflow, whether they are content creators or marketers, something to keep in mind if you aren’t the only one who will edit the content.

It is worth noting that some Headless CMS, not only focuses on offering you the services already offered by a CMS like WordPress. It also provides services such as image CDNs to resize or reformat your images on the fly, or additional security through S3 backups.

Having this setup will not only give you freedom, security and comfort, but will also improve the performance of your application without third-party services. Just by connecting your front-end project via an HTTP client and getting the components and data, you will be up and running.

The Benefits Of Going Headless And When It Makes Sense

WordPress’ architecture often does not offer the possibilities we sometimes need when working on a website, especially when it comes to optimizing performance, one of the most important points when ranking our site in a search engine like Google and especially now that Web Vitals is up and running.

But it is clear that if we have a personal site that only we ourselves work on, then it’s not necessary to migrate it to a headless setup. However, if more people are involved in that project (not just developers but content creators or marketing teams), then we should consider adopting Headless CMS.

How Can A Headless CMS Help Us Improve The Performance Of Our Website And The Quality Of Our Front-End Project?

  • By allowing you to develop the front-end in a way that is completely independent of the platform where you edit your content.

    The technology you choose is your own choice, if you wanted to upgrade your project to the latest front-end framework, you would not be dependent on a back-end and could do so without having to rethink migrations.

  • Allowing you to create multiplatform projects without having to depend on different administration panels.

    In the end, if for an app you need a shorter description than the main website, you can always make use of a new “short_description” field and just represent it on the front-end of that specific app.

  • It is intended to make development easier and simplify the process of creating a site, as well as scaling it.

    By having the front-end completely isolated we can change the visual appearance of our entire application without modifying the structure of our content.

  • Always offering services that will allow us to optimize our assets and the speed of response with which they are served to us. Ultimately all our data will be delivered through CDN networks.

A content delivery network (CDN), is a geographically distributed network of proxy servers and their data centers. The goal is to provide high availability and performance by distributing the service spatially relative to end-users.

What If We Are Concerned About How It Will Work With Our Brand’s Or Company’s Structure?

  • As well as supporting cross-platform applications, it also allows us to maintain brand consistency.

    Having the front-end as a base project and having multiples spaces in a Headless CMS, allows you to have consistency between your products and makes the scalability easier because we have less code to maintain.

  • Although not all headless CMS have this benefit, the headless CMS we are migrating to, Storyblok, has a Visual Editor, which allows creating independence among teams. The editors or content creators can access the panel to edit existing content or create new content, being able to see a preview of how it will look before publishing. So they won’t have to involve the development team in this process and can do their work more efficiently.
  • It also streamlines content management by allowing you to set up your own content workflow. You can define the stages that a piece of content must go through before being published and, only when it passes the process successfully, it will be published.

How Can A Headless CMS Save Time Compared To A Traditional CMS?

  • Taking care of maintaining the security of the platform and updating it on your behalf. Whenever there is a bug or users require a new feature, the team behind your Headless CMS will develop it for you, you just have to start using it!
  • Constantly improving the user experience (UX) and design (UI) for you, so that content creators and developers feel comfortable creating new fields, components or pages. But not only on the visual aspect, but they will also be looking to improve the performance of the database, so you get your content instantly and forget about all the work that is involved.
Monolithic vs Headless
Feature Monolithic Headless
Architecture Coupled: linked back-end front-end Decoupled: independent front-end project
Technology You will have to use the one in which the project is developed Freedom to choose your front-end technology
Cross-platform Limited to one front-end at a time Connects to any front-end projects
Content workflow Restrictive Custom
Security and updates You take care It takes care for you

Having seen the advantages that a headless setup can bring to our project and the people who work on it, I think it is time to look at the steps we need to migrate our project.

What You Need To Keep In Mind When Going Headless

As we have already mentioned, Headless CMS allow for a clean separation of concerns between content creators and developers. In this way (in a Headless CMS), the developer focuses on creating the content structure, which will be represented in the front-end project, and the editor will be in charge of using the components and filling them with content in the admin panel.

Type Of Content We Can Create In A Headless CMS

1. Types of entry or template

Similar to Custom Post Types in WordPress but with more freedom and extensibility when it comes to data types and editors.

When you go to create a new content entry in your dashboard, you expect to be able to choose what type it depends on the situation. For example, if you have a website with a blog you will want to have several types of templates, one for pages with listings or dynamic content called “page” and one for each blog entry “post“.

Depending on the headless CMS you have chosen, the name will vary but the concept is the same. In Storyblok these types of entities are called Content Type. “Content Types” define the type of content entry and can hold the basic fields for your content entries. By default, we have a “Page” content type.

2. Reusable components

In a Headless CMS, you can create, in addition to Content Types, nested components and reuse them between content types and other components. In Storyblok, this type of component — as you may have noticed from its name — is called Blok.

To use them in a Content Type such as a page, you will need to create a field in the schema of type blocks. This field allows you to add nested components to your page while adding content.

But, in principle, we will not need such components during the migration. It simply gives you the flexibility to create robust and dynamic applications without having to involve the developer.

For example, when a member of the marketing team wants to add a new Hero to the About us page, if the Hero component was created as nested and the page had a Blocks field, the marketing person could add the Hero without having to involve the developer.

Rendering The Data Coming From The Headless CMS

As we are defining the structure of our content in the Headless CMS panel, we have to consider which framework we want to create our front-end project with and which HTTP client we will use.

When choosing a framework we have to take several factors into account:

Are my team and I am familiar with this technology?

Does it allow me to render my content in the type of rendering my project needs?

Does it have plugins or modules that facilitate integration with the Headless CMS I’m using?

In most cases, a static site will be sufficient and will always be the most economical and high-performance answer. So, you just have to look for a static site generator for the technology you are familiar with, for example, Nuxt for Vue or Next for the React library.

Connecting these two things, a Headless CMS and a static site builder are considered as a set of web development best practices focused on providing the highest performance, security and lowest cost. This architecture is also known as Jamstack. It’s an architecture designed to make the web faster, more secure and easier to scale. It builds on many of the tools and workflows which developers love, and which bring maximum productivity.

By making use of the trendy frameworks, you will be assured of an integration guide with the Headless CMS you are going to work with, and most of them have already a module or package that allows you to obtain information from the API and in many cases extend it.

The only thing left for you to do is to define the structure of your components concerning how you have structured the data in your Headless CMS and automate the content publishing process. For example, using the Webhooks that the Headless CMS provides you with, you will be able to start a build process in your favourite hosting by its build hooks once the content has been published.

Amount Of Time You’ll Need

As with any migration, the time required will always depend proportionally on the complexity of your project. If we are talking about a common WordPress site you will only need to migrate the Post types that you have defined or that comes by default in it, such as Pages, Posts and Categories, and their content.

If, on the other hand, you have customized your project with multiple plugins, you will have to develop them through the front-end project or using the ones provided by your Headless CMS. For example, if we are SEO conscious and therefore make use of Yoast SEO on WordPress, we will have the Field-Type SEO plugin in Storyblok to help us in the transition, but we will still have to develop our sitemap in the front-end with a guide to help us.

In the end, all the burden of development will fall on the front-end project, as setting up the Headless CMS will not take that much time.

But let’s stop talking and let’s take a look at it!

Steps To Migrate Our Content From WordPress To Storyblok

The migration will consist of four steps, from the creation of a space in our new Headless CMS Storyblok to the representation of the migrated content in our front-end project, which we will see in detail below and in which I will leave you resources to make the migration easier for you.

Let’s get started!

1. Creating A Space In Storyblok

In order to create a space in Storyblok, you first need to have an account. To do this, you will need to select the plan that suits you best.

Go to the Pricing page and start with the plan that best suits your needs or try the free plan for testing.

Create your account, and you will be able to access the panel.

Choose ‘Create a new space’ and let’s get started!

Space is a content repository. Think of it as a place to keep all the content related to one project. Each space has its own components, data sources, assets, environments, domains, collaborators and permissions.

Take some time to explore the sections on the left sidebar. Start by browsing the following:

  • Content, this will be the folder where the content will be stored, where the marketing team will spend most of their time.
  • Assets, where all the images will be stored, which you can then get through the CDN service, optimized and of any size.
  • Components, where you will create the Content types and Nested components.
  • Settings, the section where you will be able to configure the data of your space as well as the languages of your application, the workflows you want your content to follow before being published, user permissions, etc. Let’s say that this area will be the one related to the IT team of the project.

If you still want to explore every option on the dashboard before diving into the migration, I recommend taking a look at Understanding the UI by Storyblok.

Now that you know a bit about the Storyblok ecosystem, it’s time to define what the content of our application will look like.

2. Defining Models

To migrate WordPress content to Storyblok, the next step is to create the schemas that define the WP data structure by creating Post Types in the Storyblok space.

Let’s start with pages and posts (the main Post Types in any WP site), which we’ll call page and post in Storyblok.

The schema of pages in WP contains the fields: title, slug, featured image, date, and content.

Note: To see all the fields contained in a Post Type go to the schema at WP REST API schema references.

What you need to know is that, by default, any Content Type in Storyblok will have some fields already defined for you, such as Name, Slug, Tags, First published date, and so on.

Those fields could be used to migrate the content from WP. You will only need to extend it by adding featured_image and content in the Page Content Type.

Go to the Components section in your space, click on the page created by default, remove the body field and add featured_image as type Assets > Images and content as Rich-text.

Once the page schema is ready, let’s move on to the post. For the Post Content Type, it is necessary to include more information, such as featured_image, excerpt, content, and relationships to other types such as Authors or Categories.

Since Authors and Categories will also have their own content, go to the Content section in the sidebar and create a couple of folders called authors and categories.

Each of the folders must have a default Content Type associated. To do this, in the Components section, create Author and Category as new Content Types, and then associate the Content Type relative to each folder by clicking on the three dots on the right of the folder and selecting Settings.

In this way, in the Post Content Type you can add a Single-Option or Multi-Options field with source Stories and point to the folder created for each field:

  • Authors
    This specifies the folder where they are located authors/.
  • Categories
    This specifies the folder where they are located categories/.

Note: If you want to know more about this relationship, have a look at the article Authors and Articles Relationship.

Now that you have seen how to create a couple of Content Types and how to create relationships between them, you will have to define the rest of the models following the same steps.

Adding A Content Type: Global

And you ask yourself, what about the content that all my pages will share? Like the navigation menu, footer, and other common elements?

Don’t worry, Storyblok has already thought about that and offers us a simple guide to define our global elements dynamically. It shows us how to create a global Content Type and how to use it in the Content section.

3. Migrating The Content

Now it’s time to start migrating the content you have stored. To access WP content you need to access the REST JSON API. Access the path /wp-json, if the project is deployed, or ?rest_route=/ if local.

In case neither of the two routes works, inspect the HTML of your page for a link in the head with rel="https://api.w.org/", as indicated in the WP discovery guide, and get the correct one.

To help us during the migration, the Storyblok developers have provided us with a plugin that will save us a lot of work. This plugin is called wordpress-importer, on it, it is possible to define the equivalent Content Type in Storyblok for the WP Post type to be migrated, and it will push it to our space and migrate the images to our Assets section for us.

Note: Using this script requires node ≥14.0.0 because it’s using optional chaining.

Creating The Migration Script

The first thing to do is to clone the repository. Then, install the NPM packages, using npm install or yarn, and create a file in the root of the project as migrateWPtoStoryblok.js. In order to run the script you need a script in package.json to run it, add:

"migrate": "node ./migrateWPtoStoryblok.js"

Once everything is ready, it’s time to start defining the script following the README specifications. And, as you can see, the next thing that will be needed is to find the Space_id and the OAuth token to connect to the Storyblok space.

  • The Space_id is in the Settings section of the sidebar, as soon as you click on it, you will see it on the right side.
  • To generate the OAuth token, you need to go to the top of the sidebar, click on the little arrow right next to the Storyblok logo, and go to My Account. If we scroll down we will see the Personal access tokens section, generate one, and copy it.

When you have obtained both secrets, you can add them to the beginning of the script along with the URL of the JSON API of your project:

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   token: 'storyblok-oauth-token', // My Account > Personal access tokens   space_id: 'space-id', // Settings })

As described in previous sections, the Page Content Type in Storyblok is the equivalent of the Post Type in WP pages. In the code block below, you’ll see where you’ll need to specify each.

And, once the Post Type and Content Type are defined, it is time to specify the name of the fields used in this entity type in WP and the equivalent name in Storyblok, in the schema_mapping option.

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   // ... Secrets   content_types: [     {       name: 'pages', // Post type in WP       new_content_type: 'page', // Equivalent Content type in Storyblok       folder: '', // OPTIONAL: To save all the content of the same type in a specific folder       schema_mapping: {         "title": "name", // "Field in WP": "Field in Storyblok"       }     }   ] })

Note: For the migration to work correctly, make sure that the permalinks are selected by the name of the entry and not as simple. Otherwise, the script will not create the parent-child relationship between pages.

Within the schema_mapping you can define several types of fields, these can be:

  • A simple field, such as title.
  • A sub-property of a field, like in this case the URL of the feature image.
    Note: The plugin itself takes care of migrating the images to the Storyblok space via the associated URL in links.wp:featuredmedia.0.

  • A field migrated to a nested block in Storyblok.

    Imagine you want to create a component in Storyblok to define your site’s rich text so that all post types using it have the same style and options.

    For that, you can use the object format and specify the name of the field in the Storyblok model under the field property, the name of the component you want to store inside that field, and the name of the field inside the component where the content will be migrated.

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   // ... Secrets   content_types: [     {       // ... Post type WP:Storyblok       schema_mapping: {         "title": "name", // "Field in WP": "Field in Storyblok"         "_links.wp:featuredmedia.0": "content.preview_image", // Using the dot notation you can define subproperties.         // Using nested blocks in Storyblok         "content": {           field: 'content.body_items', // Field name in Storyblok           component: "rich-text", // Component name inside the above field           component_field: "content" // Field name inside the component where you want to migrate the content         }       }     }   ] })  wp2storyblok.migrate()

Entry Type Page

Now that you know how to define the field types, for the page schema, it would look like in the code block below.

The plugin will take care of the parent-child relationship between pages by creating a folder in Storyblok under the parent’s slug and associating the parent as the home of that folder.

Furthermore, if the content field contains images, the plugin will also migrate it for you!

{   name: 'pages', // Name of the post type in WP   new_content_type: 'page', // Name of the Content Type in Storyblok   schema_mapping: {     "date": "first_published_at",     "title": "name",     "slug": "slug",     "_links.wp:featuredmedia.0": "content.featured_image",     "content": "content.content",   } }

Entry Type Post

Posts have a schema similar to pages but, in this case, to store them in a folder you must define the name of the folder below the entry type:

{   name: 'posts', // Post type name in WP   new_content_type: 'post', // Content Type name in Storyblok   folder: 'articles', // Destination folder name in Storyblok   schema_mapping: {     "date": "first_published_at",     "title": "name",     "slug": "slug",     "_links.wp:featuredmedia.0": "content.featured_image",     "excerpt": "content.excerpt",     "content": "content.content",   } }
Entry Type Category

And once the schema for posts has been defined, it makes sense to define the schema for the categories so that they can be associated as described in the previous section.

In order to define the folder that contains them as categories and not as category, their default name, you must go to the Permalinks option in the WordPress admin and change the Categories base option to categories. Then the multi-option field of the Post entries will be the one that has the relationship with the corresponding categories.

Note: These steps are the same as those to be followed for migrating authors and linking them to articles.

{   name: 'categories', // Name of the post type in WP   new_content_type: 'category', // Name of the Content Type in Storyblok   // By default will be contained by a folder called Category (change it in the Permalinks option in WP)   schema_mapping: {     "name": "name",     "slug": "slug",     "description": "content.description",     "parent": "content.parent",   } }

Full Final Script

The code below will be the resulting migration script from a WP project with the basic types to the Storyblok space we had created.

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   token: '',   space_id: 34234,   content_types: [     {       name: 'pages', // Name of the post type in WP       new_content_type: 'page', // Name of the Content Type in Storyblok       schema_mapping: {         "date": "first_published_at",         "title": "name",         "slug": "slug",         "_links.wp:featuredmedia.0": "content.featured_image",         "content": "content.content",       }     },     {       name: 'categories', // Name of the post type in WP       new_content_type: 'category', // Name of the Content Type in Storyblok       // By default will be contained by a folder called Category (change it in the Permalinks option in WP)       schema_mapping: {         "name": "name",         "slug": "slug",         "description": "content.description",         "parent": "content.parent",       }     },     // Add authors as categories.     {       name: 'posts', // Name of the post type in WP       new_content_type: 'post', // Name of the Content Type in Storyblok       folder: 'articles', // Name of the destination folder in Storyblok       schema_mapping: {         "date": "first_published_at",         "title": "name",         "slug": "slug",         "_links.wp:featuredmedia.0": "content.featured_image",         "excerpt": "content.excerpt",         "content": "content.content",       }     }     // More schemas...   ] })  wp2storyblok.migrate()

4. Create A Front-End Project

Now that the content is already stored in the Storyblok dashboard, it’s time to connect the Front-end project to Storyblok.

Whatever your framework or JS library, Storyblok provides the JavaScript client that will help you with the integration. In addition, in case you are using a specific framework, you will find other packages that will ease the way, like in Nuxt the storyblok-nuxt module.

This JavaScript API will also include a bridge between Storyblok and your Front-end application. The bridge is responsible for communicating via iframe with Storyblok to tell the editing interface which component to open when the user clicks on it.

Here is a list of tutorials you can find on Storyblok to connect your Front-end project.

Note: If you don’t find your technology among them, don’t worry there are many other tutorials on the Storyblok website, search for yours in the search engine, and if you don’t find one I encourage you to contact them, and you will help many more people!

5. Host Your Front-End Project And Automate Deploy

Once your project is ready to go into production, you choose a hosting provider and link your repository for easy deployment, then you ask yourself:

How do I redeploy my static site if I publish an entry on Storyblok?

The answer is very simple: by using the webhooks offered by Storyblok and the build hooks of your hosting.

To give you a real example, you can create build hooks URLs in Netlify within the deployment section; the URL created for Storyblok in the build hooks will go in the Settings → Webhooks → Story published & unpublished field in the Storyblok space.

Guides And Tools We Have Used During Migration

Let’s recap the links that have helped in the migration of the content and those that helped to understand the functioning of the REST API and the headless CMS to which you are migrating.

WP REST API Documentation Needed

REST API
Schemas

Migrating To Storyblok

General Info
Documentation
Global Components
SEO Related
Webhooks And Build Hooks
Scripts And Packages

Jamstack

Conclusion

After reading this article you will have what you need to understand why a headless setup will improve your project, how to migrate from your WordPress project to a headless CMS like Storyblok and how to keep improving and extending your project.

As you have seen, the possibilities of a headless setup are endless. After the migration, you will have enormous flexibility to scale your project, improve its performance and SEO, increase the productivity of the development team and stay on top of the latest trends.

Everyone is starting to migrate and there is more and more content and scripts that make it easier. What are you waiting for to migrate your WordPress?

Articles on Smashing Magazine — For Web Designers And Developers

21 Jul

How To Migrate From WordPress To A Headless CMS

by TBSCategories: News

WordPress is the most used website builder in the world; almost half of the web has used WordPress to create their website. It makes sense, because it allows you to quickly create websites and has a rich plugin’s ecosystem to help you scale your site.

But technology is evolving, and there are more and more options that make it easier to create websites. Moreover, they give us the possibility to improve the website’s performance and to have more control and security over the application.

The initial WordPress architecture is monolithic, so the user interface and data access are combined on the same platform.

Since the introduction of the REST API on WordPress, it can be used in a headless way, allowing developers to use it as a backend and having the front-end in a different project.

In this decoupled way, models and controllers are bundled on the WordPress side, handling data manipulation and database interaction. Meanwhile, the front-end only interacts with the REST API via an HTTP client.

But this also has some disadvantages, you still need to configure and update WordPress, make it secure and are dependent on their technology for the development of new functionalities.

Related Reading on SmashingMag

For those of you who are just starting in the headless world, these articles will help you understand the ins and outs behind it and why everyone is starting to migrate.

But Why Migrate To A Headless CMS?

Taking into account that this article will showcase how to migrate from WordPress to a Headless CMS, WordPress is probably your current setup.

A Headless CMS will give us the freedom to focus only on the front-end project, being able to choose the technology we are familiar with, and on the structure of our data. In the end, it takes care of the content management and the content delivery, so that we can take care of the rendering part.

“A Headless CMS is a system that provides the same features as a Content Management System (CMS) and more, all exposed through an API.”

This type of setup is especially useful for companies that have multiple sites and want to reduce costs or simplify processes. A headless architecture allows these companies to centralize content management in a single administration interface, providing the APIs that will be consumed by the company’s different web pages.

Another common use of a headless architecture is to create a front-end project that represents the company brand. In this way, all the products that the company launches will have the same look and feel, but each one will have its own content, managed in the same administration panel.

Note: This example can be easily seen on conference websites such as JSWorld Conference and VueJS Amsterdam which, being from the same creators, the front-end project is the same, only the content changes.

Different to a CMS like WordPress, in a Headless CMS you have an administration panel already configured and maintained, and sometimes also hosted, for you. To start creating content, you just need to create an account, log in, and you will be able to create, edit, duplicate and delete your content, manage users, translate content and work with publication workflows, among other things.

A headless CMS will make it easier for the people in your team to understand the workflow, whether they are content creators or marketers, something to keep in mind if you aren’t the only one who will edit the content.

It is worth noting that some Headless CMS, not only focuses on offering you the services already offered by a CMS like WordPress. It also provides services such as image CDNs to resize or reformat your images on the fly, or additional security through S3 backups.

Having this setup will not only give you freedom, security and comfort, but will also improve the performance of your application without third-party services. Just by connecting your front-end project via an HTTP client and getting the components and data, you will be up and running.

The Benefits Of Going Headless And When It Makes Sense

WordPress’ architecture often does not offer the possibilities we sometimes need when working on a website, especially when it comes to optimizing performance, one of the most important points when ranking our site in a search engine like Google and especially now that Web Vitals is up and running.

But it is clear that if we have a personal site that only we ourselves work on, then it’s not necessary to migrate it to a headless setup. However, if more people are involved in that project (not just developers but content creators or marketing teams), then we should consider adopting Headless CMS.

How Can A Headless CMS Help Us Improve The Performance Of Our Website And The Quality Of Our Front-End Project?

  • By allowing you to develop the front-end in a way that is completely independent of the platform where you edit your content.

    The technology you choose is your own choice, if you wanted to upgrade your project to the latest front-end framework, you would not be dependent on a back-end and could do so without having to rethink migrations.

  • Allowing you to create multiplatform projects without having to depend on different administration panels.

    In the end, if for an app you need a shorter description than the main website, you can always make use of a new “short_description” field and just represent it on the front-end of that specific app.

  • It is intended to make development easier and simplify the process of creating a site, as well as scaling it.

    By having the front-end completely isolated we can change the visual appearance of our entire application without modifying the structure of our content.

  • Always offering services that will allow us to optimize our assets and the speed of response with which they are served to us. Ultimately all our data will be delivered through CDN networks.

A content delivery network (CDN), is a geographically distributed network of proxy servers and their data centers. The goal is to provide high availability and performance by distributing the service spatially relative to end-users.

What If We Are Concerned About How It Will Work With Our Brand’s Or Company’s Structure?

  • As well as supporting cross-platform applications, it also allows us to maintain brand consistency.

    Having the front-end as a base project and having multiples spaces in a Headless CMS, allows you to have consistency between your products and makes the scalability easier because we have less code to maintain.

  • Although not all headless CMS have this benefit, the headless CMS we are migrating to, Storyblok, has a Visual Editor, which allows creating independence among teams. The editors or content creators can access the panel to edit existing content or create new content, being able to see a preview of how it will look before publishing. So they won’t have to involve the development team in this process and can do their work more efficiently.
  • It also streamlines content management by allowing you to set up your own content workflow. You can define the stages that a piece of content must go through before being published and, only when it passes the process successfully, it will be published.

How Can A Headless CMS Save Time Compared To A Traditional CMS?

  • Taking care of maintaining the security of the platform and updating it on your behalf. Whenever there is a bug or users require a new feature, the team behind your Headless CMS will develop it for you, you just have to start using it!
  • Constantly improving the user experience (UX) and design (UI) for you, so that content creators and developers feel comfortable creating new fields, components or pages. But not only on the visual aspect, but they will also be looking to improve the performance of the database, so you get your content instantly and forget about all the work that is involved.
Monolithic vs Headless
Feature Monolithic Headless
Architecture Coupled: linked back-end front-end Decoupled: independent front-end project
Technology You will have to use the one in which the project is developed Freedom to choose your front-end technology
Cross-platform Limited to one front-end at a time Connects to any front-end projects
Content workflow Restrictive Custom
Security and updates You take care It takes care for you

Having seen the advantages that a headless setup can bring to our project and the people who work on it, I think it is time to look at the steps we need to migrate our project.

What You Need To Keep In Mind When Going Headless

As we have already mentioned, Headless CMS allow for a clean separation of concerns between content creators and developers. In this way (in a Headless CMS), the developer focuses on creating the content structure, which will be represented in the front-end project, and the editor will be in charge of using the components and filling them with content in the admin panel.

Type Of Content We Can Create In A Headless CMS

1. Types of entry or template

Similar to Custom Post Types in WordPress but with more freedom and extensibility when it comes to data types and editors.

When you go to create a new content entry in your dashboard, you expect to be able to choose what type it depends on the situation. For example, if you have a website with a blog you will want to have several types of templates, one for pages with listings or dynamic content called “page” and one for each blog entry “post“.

Depending on the headless CMS you have chosen, the name will vary but the concept is the same. In Storyblok these types of entities are called Content Type. “Content Types” define the type of content entry and can hold the basic fields for your content entries. By default, we have a “Page” content type.

2. Reusable components

In a Headless CMS, you can create, in addition to Content Types, nested components and reuse them between content types and other components. In Storyblok, this type of component — as you may have noticed from its name — is called Blok.

To use them in a Content Type such as a page, you will need to create a field in the schema of type blocks. This field allows you to add nested components to your page while adding content.

But, in principle, we will not need such components during the migration. It simply gives you the flexibility to create robust and dynamic applications without having to involve the developer.

For example, when a member of the marketing team wants to add a new Hero to the About us page, if the Hero component was created as nested and the page had a Blocks field, the marketing person could add the Hero without having to involve the developer.

Rendering The Data Coming From The Headless CMS

As we are defining the structure of our content in the Headless CMS panel, we have to consider which framework we want to create our front-end project with and which HTTP client we will use.

When choosing a framework we have to take several factors into account:

Are my team and I am familiar with this technology?

Does it allow me to render my content in the type of rendering my project needs?

Does it have plugins or modules that facilitate integration with the Headless CMS I’m using?

In most cases, a static site will be sufficient and will always be the most economical and high-performance answer. So, you just have to look for a static site generator for the technology you are familiar with, for example, Nuxt for Vue or Next for the React library.

Connecting these two things, a Headless CMS and a static site builder are considered as a set of web development best practices focused on providing the highest performance, security and lowest cost. This architecture is also known as Jamstack. It’s an architecture designed to make the web faster, more secure and easier to scale. It builds on many of the tools and workflows which developers love, and which bring maximum productivity.

By making use of the trendy frameworks, you will be assured of an integration guide with the Headless CMS you are going to work with, and most of them have already a module or package that allows you to obtain information from the API and in many cases extend it.

The only thing left for you to do is to define the structure of your components concerning how you have structured the data in your Headless CMS and automate the content publishing process. For example, using the Webhooks that the Headless CMS provides you with, you will be able to start a build process in your favourite hosting by its build hooks once the content has been published.

Amount Of Time You’ll Need

As with any migration, the time required will always depend proportionally on the complexity of your project. If we are talking about a common WordPress site you will only need to migrate the Post types that you have defined or that comes by default in it, such as Pages, Posts and Categories, and their content.

If, on the other hand, you have customized your project with multiple plugins, you will have to develop them through the front-end project or using the ones provided by your Headless CMS. For example, if we are SEO conscious and therefore make use of Yoast SEO on WordPress, we will have the Field-Type SEO plugin in Storyblok to help us in the transition, but we will still have to develop our sitemap in the front-end with a guide to help us.

In the end, all the burden of development will fall on the front-end project, as setting up the Headless CMS will not take that much time.

But let’s stop talking and let’s take a look at it!

Steps To Migrate Our Content From WordPress To Storyblok

The migration will consist of four steps, from the creation of a space in our new Headless CMS Storyblok to the representation of the migrated content in our front-end project, which we will see in detail below and in which I will leave you resources to make the migration easier for you.

Let’s get started!

1. Creating A Space In Storyblok

In order to create a space in Storyblok, you first need to have an account. To do this, you will need to select the plan that suits you best.

Go to the Pricing page and start with the plan that best suits your needs or try the free plan for testing.

Create your account, and you will be able to access the panel.

Choose ‘Create a new space’ and let’s get started!

Space is a content repository. Think of it as a place to keep all the content related to one project. Each space has its own components, data sources, assets, environments, domains, collaborators and permissions.

Take some time to explore the sections on the left sidebar. Start by browsing the following:

  • Content, this will be the folder where the content will be stored, where the marketing team will spend most of their time.
  • Assets, where all the images will be stored, which you can then get through the CDN service, optimized and of any size.
  • Components, where you will create the Content types and Nested components.
  • Settings, the section where you will be able to configure the data of your space as well as the languages of your application, the workflows you want your content to follow before being published, user permissions, etc. Let’s say that this area will be the one related to the IT team of the project.

If you still want to explore every option on the dashboard before diving into the migration, I recommend taking a look at Understanding the UI by Storyblok.

Now that you know a bit about the Storyblok ecosystem, it’s time to define what the content of our application will look like.

2. Defining Models

To migrate WordPress content to Storyblok, the next step is to create the schemas that define the WP data structure by creating Post Types in the Storyblok space.

Let’s start with pages and posts (the main Post Types in any WP site), which we’ll call page and post in Storyblok.

The schema of pages in WP contains the fields: title, slug, featured image, date, and content.

Note: To see all the fields contained in a Post Type go to the schema at WP REST API schema references.

What you need to know is that, by default, any Content Type in Storyblok will have some fields already defined for you, such as Name, Slug, Tags, First published date, and so on.

Those fields could be used to migrate the content from WP. You will only need to extend it by adding featured_image and content in the Page Content Type.

Go to the Components section in your space, click on the page created by default, remove the body field and add featured_image as type Assets > Images and content as Rich-text.

Once the page schema is ready, let’s move on to the post. For the Post Content Type, it is necessary to include more information, such as featured_image, excerpt, content, and relationships to other types such as Authors or Categories.

Since Authors and Categories will also have their own content, go to the Content section in the sidebar and create a couple of folders called authors and categories.

Each of the folders must have a default Content Type associated. To do this, in the Components section, create Author and Category as new Content Types, and then associate the Content Type relative to each folder by clicking on the three dots on the right of the folder and selecting Settings.

In this way, in the Post Content Type you can add a Single-Option or Multi-Options field with source Stories and point to the folder created for each field:

  • Authors
    This specifies the folder where they are located authors/.
  • Categories
    This specifies the folder where they are located categories/.

Note: If you want to know more about this relationship, have a look at the article Authors and Articles Relationship.

Now that you have seen how to create a couple of Content Types and how to create relationships between them, you will have to define the rest of the models following the same steps.

Adding A Content Type: Global

And you ask yourself, what about the content that all my pages will share? Like the navigation menu, footer, and other common elements?

Don’t worry, Storyblok has already thought about that and offers us a simple guide to define our global elements dynamically. It shows us how to create a global Content Type and how to use it in the Content section.

3. Migrating The Content

Now it’s time to start migrating the content you have stored. To access WP content you need to access the REST JSON API. Access the path /wp-json, if the project is deployed, or ?rest_route=/ if local.

In case neither of the two routes works, inspect the HTML of your page for a link in the head with rel="https://api.w.org/", as indicated in the WP discovery guide, and get the correct one.

To help us during the migration, the Storyblok developers have provided us with a plugin that will save us a lot of work. This plugin is called wordpress-importer, on it, it is possible to define the equivalent Content Type in Storyblok for the WP Post type to be migrated, and it will push it to our space and migrate the images to our Assets section for us.

Note: Using this script requires node ≥14.0.0 because it’s using optional chaining.

Creating The Migration Script

The first thing to do is to clone the repository. Then, install the NPM packages, using npm install or yarn, and create a file in the root of the project as migrateWPtoStoryblok.js. In order to run the script you need a script in package.json to run it, add:

"migrate": "node ./migrateWPtoStoryblok.js"

Once everything is ready, it’s time to start defining the script following the README specifications. And, as you can see, the next thing that will be needed is to find the Space_id and the OAuth token to connect to the Storyblok space.

  • The Space_id is in the Settings section of the sidebar, as soon as you click on it, you will see it on the right side.
  • To generate the OAuth token, you need to go to the top of the sidebar, click on the little arrow right next to the Storyblok logo, and go to My Account. If we scroll down we will see the Personal access tokens section, generate one, and copy it.

When you have obtained both secrets, you can add them to the beginning of the script along with the URL of the JSON API of your project:

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   token: 'storyblok-oauth-token', // My Account > Personal access tokens   space_id: 'space-id', // Settings })

As described in previous sections, the Page Content Type in Storyblok is the equivalent of the Post Type in WP pages. In the code block below, you’ll see where you’ll need to specify each.

And, once the Post Type and Content Type are defined, it is time to specify the name of the fields used in this entity type in WP and the equivalent name in Storyblok, in the schema_mapping option.

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   // ... Secrets   content_types: [     {       name: 'pages', // Post type in WP       new_content_type: 'page', // Equivalent Content type in Storyblok       folder: '', // OPTIONAL: To save all the content of the same type in a specific folder       schema_mapping: {         "title": "name", // "Field in WP": "Field in Storyblok"       }     }   ] })

Note: For the migration to work correctly, make sure that the permalinks are selected by the name of the entry and not as simple. Otherwise, the script will not create the parent-child relationship between pages.

Within the schema_mapping you can define several types of fields, these can be:

  • A simple field, such as title.
  • A sub-property of a field, like in this case the URL of the feature image.
    Note: The plugin itself takes care of migrating the images to the Storyblok space via the associated URL in links.wp:featuredmedia.0.

  • A field migrated to a nested block in Storyblok.

    Imagine you want to create a component in Storyblok to define your site’s rich text so that all post types using it have the same style and options.

    For that, you can use the object format and specify the name of the field in the Storyblok model under the field property, the name of the component you want to store inside that field, and the name of the field inside the component where the content will be migrated.

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   // ... Secrets   content_types: [     {       // ... Post type WP:Storyblok       schema_mapping: {         "title": "name", // "Field in WP": "Field in Storyblok"         "_links.wp:featuredmedia.0": "content.preview_image", // Using the dot notation you can define subproperties.         // Using nested blocks in Storyblok         "content": {           field: 'content.body_items', // Field name in Storyblok           component: "rich-text", // Component name inside the above field           component_field: "content" // Field name inside the component where you want to migrate the content         }       }     }   ] })  wp2storyblok.migrate()

Entry Type Page

Now that you know how to define the field types, for the page schema, it would look like in the code block below.

The plugin will take care of the parent-child relationship between pages by creating a folder in Storyblok under the parent’s slug and associating the parent as the home of that folder.

Furthermore, if the content field contains images, the plugin will also migrate it for you!

{   name: 'pages', // Name of the post type in WP   new_content_type: 'page', // Name of the Content Type in Storyblok   schema_mapping: {     "date": "first_published_at",     "title": "name",     "slug": "slug",     "_links.wp:featuredmedia.0": "content.featured_image",     "content": "content.content",   } }

Entry Type Post

Posts have a schema similar to pages but, in this case, to store them in a folder you must define the name of the folder below the entry type:

{   name: 'posts', // Post type name in WP   new_content_type: 'post', // Content Type name in Storyblok   folder: 'articles', // Destination folder name in Storyblok   schema_mapping: {     "date": "first_published_at",     "title": "name",     "slug": "slug",     "_links.wp:featuredmedia.0": "content.featured_image",     "excerpt": "content.excerpt",     "content": "content.content",   } }
Entry Type Category

And once the schema for posts has been defined, it makes sense to define the schema for the categories so that they can be associated as described in the previous section.

In order to define the folder that contains them as categories and not as category, their default name, you must go to the Permalinks option in the WordPress admin and change the Categories base option to categories. Then the multi-option field of the Post entries will be the one that has the relationship with the corresponding categories.

Note: These steps are the same as those to be followed for migrating authors and linking them to articles.

{   name: 'categories', // Name of the post type in WP   new_content_type: 'category', // Name of the Content Type in Storyblok   // By default will be contained by a folder called Category (change it in the Permalinks option in WP)   schema_mapping: {     "name": "name",     "slug": "slug",     "description": "content.description",     "parent": "content.parent",   } }

Full Final Script

The code below will be the resulting migration script from a WP project with the basic types to the Storyblok space we had created.

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   token: '',   space_id: 34234,   content_types: [     {       name: 'pages', // Name of the post type in WP       new_content_type: 'page', // Name of the Content Type in Storyblok       schema_mapping: {         "date": "first_published_at",         "title": "name",         "slug": "slug",         "_links.wp:featuredmedia.0": "content.featured_image",         "content": "content.content",       }     },     {       name: 'categories', // Name of the post type in WP       new_content_type: 'category', // Name of the Content Type in Storyblok       // By default will be contained by a folder called Category (change it in the Permalinks option in WP)       schema_mapping: {         "name": "name",         "slug": "slug",         "description": "content.description",         "parent": "content.parent",       }     },     // Add authors as categories.     {       name: 'posts', // Name of the post type in WP       new_content_type: 'post', // Name of the Content Type in Storyblok       folder: 'articles', // Name of the destination folder in Storyblok       schema_mapping: {         "date": "first_published_at",         "title": "name",         "slug": "slug",         "_links.wp:featuredmedia.0": "content.featured_image",         "excerpt": "content.excerpt",         "content": "content.content",       }     }     // More schemas...   ] })  wp2storyblok.migrate()

4. Create A Front-End Project

Now that the content is already stored in the Storyblok dashboard, it’s time to connect the Front-end project to Storyblok.

Whatever your framework or JS library, Storyblok provides the JavaScript client that will help you with the integration. In addition, in case you are using a specific framework, you will find other packages that will ease the way, like in Nuxt the storyblok-nuxt module.

This JavaScript API will also include a bridge between Storyblok and your Front-end application. The bridge is responsible for communicating via iframe with Storyblok to tell the editing interface which component to open when the user clicks on it.

Here is a list of tutorials you can find on Storyblok to connect your Front-end project.

Note: If you don’t find your technology among them, don’t worry there are many other tutorials on the Storyblok website, search for yours in the search engine, and if you don’t find one I encourage you to contact them, and you will help many more people!

5. Host Your Front-End Project And Automate Deploy

Once your project is ready to go into production, you choose a hosting provider and link your repository for easy deployment, then you ask yourself:

How do I redeploy my static site if I publish an entry on Storyblok?

The answer is very simple: by using the webhooks offered by Storyblok and the build hooks of your hosting.

To give you a real example, you can create build hooks URLs in Netlify within the deployment section; the URL created for Storyblok in the build hooks will go in the Settings → Webhooks → Story published & unpublished field in the Storyblok space.

Guides And Tools We Have Used During Migration

Let’s recap the links that have helped in the migration of the content and those that helped to understand the functioning of the REST API and the headless CMS to which you are migrating.

WP REST API Documentation Needed

REST API
Schemas

Migrating To Storyblok

General Info
Documentation
Global Components
SEO Related
Webhooks And Build Hooks
Scripts And Packages

Jamstack

Conclusion

After reading this article you will have what you need to understand why a headless setup will improve your project, how to migrate from your WordPress project to a headless CMS like Storyblok and how to keep improving and extending your project.

As you have seen, the possibilities of a headless setup are endless. After the migration, you will have enormous flexibility to scale your project, improve its performance and SEO, increase the productivity of the development team and stay on top of the latest trends.

Everyone is starting to migrate and there is more and more content and scripts that make it easier. What are you waiting for to migrate your WordPress?

Articles on Smashing Magazine — For Web Designers And Developers

21 Jul

How To Migrate From WordPress To A Headless CMS

by TBSCategories: News

WordPress is the most used website builder in the world; almost half of the web has used WordPress to create their website. It makes sense, because it allows you to quickly create websites and has a rich plugin’s ecosystem to help you scale your site.

But technology is evolving, and there are more and more options that make it easier to create websites. Moreover, they give us the possibility to improve the website’s performance and to have more control and security over the application.

The initial WordPress architecture is monolithic, so the user interface and data access are combined on the same platform.

Since the introduction of the REST API on WordPress, it can be used in a headless way, allowing developers to use it as a backend and having the front-end in a different project.

In this decoupled way, models and controllers are bundled on the WordPress side, handling data manipulation and database interaction. Meanwhile, the front-end only interacts with the REST API via an HTTP client.

But this also has some disadvantages, you still need to configure and update WordPress, make it secure and are dependent on their technology for the development of new functionalities.

Related Reading on SmashingMag

For those of you who are just starting in the headless world, these articles will help you understand the ins and outs behind it and why everyone is starting to migrate.

But Why Migrate To A Headless CMS?

Taking into account that this article will showcase how to migrate from WordPress to a Headless CMS, WordPress is probably your current setup.

A Headless CMS will give us the freedom to focus only on the front-end project, being able to choose the technology we are familiar with, and on the structure of our data. In the end, it takes care of the content management and the content delivery, so that we can take care of the rendering part.

“A Headless CMS is a system that provides the same features as a Content Management System (CMS) and more, all exposed through an API.”

This type of setup is especially useful for companies that have multiple sites and want to reduce costs or simplify processes. A headless architecture allows these companies to centralize content management in a single administration interface, providing the APIs that will be consumed by the company’s different web pages.

Another common use of a headless architecture is to create a front-end project that represents the company brand. In this way, all the products that the company launches will have the same look and feel, but each one will have its own content, managed in the same administration panel.

Note: This example can be easily seen on conference websites such as JSWorld Conference and VueJS Amsterdam which, being from the same creators, the front-end project is the same, only the content changes.

Different to a CMS like WordPress, in a Headless CMS you have an administration panel already configured and maintained, and sometimes also hosted, for you. To start creating content, you just need to create an account, log in, and you will be able to create, edit, duplicate and delete your content, manage users, translate content and work with publication workflows, among other things.

A headless CMS will make it easier for the people in your team to understand the workflow, whether they are content creators or marketers, something to keep in mind if you aren’t the only one who will edit the content.

It is worth noting that some Headless CMS, not only focuses on offering you the services already offered by a CMS like WordPress. It also provides services such as image CDNs to resize or reformat your images on the fly, or additional security through S3 backups.

Having this setup will not only give you freedom, security and comfort, but will also improve the performance of your application without third-party services. Just by connecting your front-end project via an HTTP client and getting the components and data, you will be up and running.

The Benefits Of Going Headless And When It Makes Sense

WordPress’ architecture often does not offer the possibilities we sometimes need when working on a website, especially when it comes to optimizing performance, one of the most important points when ranking our site in a search engine like Google and especially now that Web Vitals is up and running.

But it is clear that if we have a personal site that only we ourselves work on, then it’s not necessary to migrate it to a headless setup. However, if more people are involved in that project (not just developers but content creators or marketing teams), then we should consider adopting Headless CMS.

How Can A Headless CMS Help Us Improve The Performance Of Our Website And The Quality Of Our Front-End Project?

  • By allowing you to develop the front-end in a way that is completely independent of the platform where you edit your content.

    The technology you choose is your own choice, if you wanted to upgrade your project to the latest front-end framework, you would not be dependent on a back-end and could do so without having to rethink migrations.

  • Allowing you to create multiplatform projects without having to depend on different administration panels.

    In the end, if for an app you need a shorter description than the main website, you can always make use of a new “short_description” field and just represent it on the front-end of that specific app.

  • It is intended to make development easier and simplify the process of creating a site, as well as scaling it.

    By having the front-end completely isolated we can change the visual appearance of our entire application without modifying the structure of our content.

  • Always offering services that will allow us to optimize our assets and the speed of response with which they are served to us. Ultimately all our data will be delivered through CDN networks.

A content delivery network (CDN), is a geographically distributed network of proxy servers and their data centers. The goal is to provide high availability and performance by distributing the service spatially relative to end-users.

What If We Are Concerned About How It Will Work With Our Brand’s Or Company’s Structure?

  • As well as supporting cross-platform applications, it also allows us to maintain brand consistency.

    Having the front-end as a base project and having multiples spaces in a Headless CMS, allows you to have consistency between your products and makes the scalability easier because we have less code to maintain.

  • Although not all headless CMS have this benefit, the headless CMS we are migrating to, Storyblok, has a Visual Editor, which allows creating independence among teams. The editors or content creators can access the panel to edit existing content or create new content, being able to see a preview of how it will look before publishing. So they won’t have to involve the development team in this process and can do their work more efficiently.
  • It also streamlines content management by allowing you to set up your own content workflow. You can define the stages that a piece of content must go through before being published and, only when it passes the process successfully, it will be published.

How Can A Headless CMS Save Time Compared To A Traditional CMS?

  • Taking care of maintaining the security of the platform and updating it on your behalf. Whenever there is a bug or users require a new feature, the team behind your Headless CMS will develop it for you, you just have to start using it!
  • Constantly improving the user experience (UX) and design (UI) for you, so that content creators and developers feel comfortable creating new fields, components or pages. But not only on the visual aspect, but they will also be looking to improve the performance of the database, so you get your content instantly and forget about all the work that is involved.
Monolithic vs Headless
Feature Monolithic Headless
Architecture Coupled: linked back-end front-end Decoupled: independent front-end project
Technology You will have to use the one in which the project is developed Freedom to choose your front-end technology
Cross-platform Limited to one front-end at a time Connects to any front-end projects
Content workflow Restrictive Custom
Security and updates You take care It takes care for you

Having seen the advantages that a headless setup can bring to our project and the people who work on it, I think it is time to look at the steps we need to migrate our project.

What You Need To Keep In Mind When Going Headless

As we have already mentioned, Headless CMS allow for a clean separation of concerns between content creators and developers. In this way (in a Headless CMS), the developer focuses on creating the content structure, which will be represented in the front-end project, and the editor will be in charge of using the components and filling them with content in the admin panel.

Type Of Content We Can Create In A Headless CMS

1. Types of entry or template

Similar to Custom Post Types in WordPress but with more freedom and extensibility when it comes to data types and editors.

When you go to create a new content entry in your dashboard, you expect to be able to choose what type it depends on the situation. For example, if you have a website with a blog you will want to have several types of templates, one for pages with listings or dynamic content called “page” and one for each blog entry “post“.

Depending on the headless CMS you have chosen, the name will vary but the concept is the same. In Storyblok these types of entities are called Content Type. “Content Types” define the type of content entry and can hold the basic fields for your content entries. By default, we have a “Page” content type.

2. Reusable components

In a Headless CMS, you can create, in addition to Content Types, nested components and reuse them between content types and other components. In Storyblok, this type of component — as you may have noticed from its name — is called Blok.

To use them in a Content Type such as a page, you will need to create a field in the schema of type blocks. This field allows you to add nested components to your page while adding content.

But, in principle, we will not need such components during the migration. It simply gives you the flexibility to create robust and dynamic applications without having to involve the developer.

For example, when a member of the marketing team wants to add a new Hero to the About us page, if the Hero component was created as nested and the page had a Blocks field, the marketing person could add the Hero without having to involve the developer.

Rendering The Data Coming From The Headless CMS

As we are defining the structure of our content in the Headless CMS panel, we have to consider which framework we want to create our front-end project with and which HTTP client we will use.

When choosing a framework we have to take several factors into account:

Are my team and I am familiar with this technology?

Does it allow me to render my content in the type of rendering my project needs?

Does it have plugins or modules that facilitate integration with the Headless CMS I’m using?

In most cases, a static site will be sufficient and will always be the most economical and high-performance answer. So, you just have to look for a static site generator for the technology you are familiar with, for example, Nuxt for Vue or Next for the React library.

Connecting these two things, a Headless CMS and a static site builder are considered as a set of web development best practices focused on providing the highest performance, security and lowest cost. This architecture is also known as Jamstack. It’s an architecture designed to make the web faster, more secure and easier to scale. It builds on many of the tools and workflows which developers love, and which bring maximum productivity.

By making use of the trendy frameworks, you will be assured of an integration guide with the Headless CMS you are going to work with, and most of them have already a module or package that allows you to obtain information from the API and in many cases extend it.

The only thing left for you to do is to define the structure of your components concerning how you have structured the data in your Headless CMS and automate the content publishing process. For example, using the Webhooks that the Headless CMS provides you with, you will be able to start a build process in your favourite hosting by its build hooks once the content has been published.

Amount Of Time You’ll Need

As with any migration, the time required will always depend proportionally on the complexity of your project. If we are talking about a common WordPress site you will only need to migrate the Post types that you have defined or that comes by default in it, such as Pages, Posts and Categories, and their content.

If, on the other hand, you have customized your project with multiple plugins, you will have to develop them through the front-end project or using the ones provided by your Headless CMS. For example, if we are SEO conscious and therefore make use of Yoast SEO on WordPress, we will have the Field-Type SEO plugin in Storyblok to help us in the transition, but we will still have to develop our sitemap in the front-end with a guide to help us.

In the end, all the burden of development will fall on the front-end project, as setting up the Headless CMS will not take that much time.

But let’s stop talking and let’s take a look at it!

Steps To Migrate Our Content From WordPress To Storyblok

The migration will consist of four steps, from the creation of a space in our new Headless CMS Storyblok to the representation of the migrated content in our front-end project, which we will see in detail below and in which I will leave you resources to make the migration easier for you.

Let’s get started!

1. Creating A Space In Storyblok

In order to create a space in Storyblok, you first need to have an account. To do this, you will need to select the plan that suits you best.

Go to the Pricing page and start with the plan that best suits your needs or try the free plan for testing.

Create your account, and you will be able to access the panel.

Choose ‘Create a new space’ and let’s get started!

Space is a content repository. Think of it as a place to keep all the content related to one project. Each space has its own components, data sources, assets, environments, domains, collaborators and permissions.

Take some time to explore the sections on the left sidebar. Start by browsing the following:

  • Content, this will be the folder where the content will be stored, where the marketing team will spend most of their time.
  • Assets, where all the images will be stored, which you can then get through the CDN service, optimized and of any size.
  • Components, where you will create the Content types and Nested components.
  • Settings, the section where you will be able to configure the data of your space as well as the languages of your application, the workflows you want your content to follow before being published, user permissions, etc. Let’s say that this area will be the one related to the IT team of the project.

If you still want to explore every option on the dashboard before diving into the migration, I recommend taking a look at Understanding the UI by Storyblok.

Now that you know a bit about the Storyblok ecosystem, it’s time to define what the content of our application will look like.

2. Defining Models

To migrate WordPress content to Storyblok, the next step is to create the schemas that define the WP data structure by creating Post Types in the Storyblok space.

Let’s start with pages and posts (the main Post Types in any WP site), which we’ll call page and post in Storyblok.

The schema of pages in WP contains the fields: title, slug, featured image, date, and content.

Note: To see all the fields contained in a Post Type go to the schema at WP REST API schema references.

What you need to know is that, by default, any Content Type in Storyblok will have some fields already defined for you, such as Name, Slug, Tags, First published date, and so on.

Those fields could be used to migrate the content from WP. You will only need to extend it by adding featured_image and content in the Page Content Type.

Go to the Components section in your space, click on the page created by default, remove the body field and add featured_image as type Assets > Images and content as Rich-text.

Once the page schema is ready, let’s move on to the post. For the Post Content Type, it is necessary to include more information, such as featured_image, excerpt, content, and relationships to other types such as Authors or Categories.

Since Authors and Categories will also have their own content, go to the Content section in the sidebar and create a couple of folders called authors and categories.

Each of the folders must have a default Content Type associated. To do this, in the Components section, create Author and Category as new Content Types, and then associate the Content Type relative to each folder by clicking on the three dots on the right of the folder and selecting Settings.

In this way, in the Post Content Type you can add a Single-Option or Multi-Options field with source Stories and point to the folder created for each field:

  • Authors
    This specifies the folder where they are located authors/.
  • Categories
    This specifies the folder where they are located categories/.

Note: If you want to know more about this relationship, have a look at the article Authors and Articles Relationship.

Now that you have seen how to create a couple of Content Types and how to create relationships between them, you will have to define the rest of the models following the same steps.

Adding A Content Type: Global

And you ask yourself, what about the content that all my pages will share? Like the navigation menu, footer, and other common elements?

Don’t worry, Storyblok has already thought about that and offers us a simple guide to define our global elements dynamically. It shows us how to create a global Content Type and how to use it in the Content section.

3. Migrating The Content

Now it’s time to start migrating the content you have stored. To access WP content you need to access the REST JSON API. Access the path /wp-json, if the project is deployed, or ?rest_route=/ if local.

In case neither of the two routes works, inspect the HTML of your page for a link in the head with rel="https://api.w.org/", as indicated in the WP discovery guide, and get the correct one.

To help us during the migration, the Storyblok developers have provided us with a plugin that will save us a lot of work. This plugin is called wordpress-importer, on it, it is possible to define the equivalent Content Type in Storyblok for the WP Post type to be migrated, and it will push it to our space and migrate the images to our Assets section for us.

Note: Using this script requires node ≥14.0.0 because it’s using optional chaining.

Creating The Migration Script

The first thing to do is to clone the repository. Then, install the NPM packages, using npm install or yarn, and create a file in the root of the project as migrateWPtoStoryblok.js. In order to run the script you need a script in package.json to run it, add:

"migrate": "node ./migrateWPtoStoryblok.js"

Once everything is ready, it’s time to start defining the script following the README specifications. And, as you can see, the next thing that will be needed is to find the Space_id and the OAuth token to connect to the Storyblok space.

  • The Space_id is in the Settings section of the sidebar, as soon as you click on it, you will see it on the right side.
  • To generate the OAuth token, you need to go to the top of the sidebar, click on the little arrow right next to the Storyblok logo, and go to My Account. If we scroll down we will see the Personal access tokens section, generate one, and copy it.

When you have obtained both secrets, you can add them to the beginning of the script along with the URL of the JSON API of your project:

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   token: 'storyblok-oauth-token', // My Account > Personal access tokens   space_id: 'space-id', // Settings })

As described in previous sections, the Page Content Type in Storyblok is the equivalent of the Post Type in WP pages. In the code block below, you’ll see where you’ll need to specify each.

And, once the Post Type and Content Type are defined, it is time to specify the name of the fields used in this entity type in WP and the equivalent name in Storyblok, in the schema_mapping option.

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   // ... Secrets   content_types: [     {       name: 'pages', // Post type in WP       new_content_type: 'page', // Equivalent Content type in Storyblok       folder: '', // OPTIONAL: To save all the content of the same type in a specific folder       schema_mapping: {         "title": "name", // "Field in WP": "Field in Storyblok"       }     }   ] })

Note: For the migration to work correctly, make sure that the permalinks are selected by the name of the entry and not as simple. Otherwise, the script will not create the parent-child relationship between pages.

Within the schema_mapping you can define several types of fields, these can be:

  • A simple field, such as title.
  • A sub-property of a field, like in this case the URL of the feature image.
    Note: The plugin itself takes care of migrating the images to the Storyblok space via the associated URL in links.wp:featuredmedia.0.

  • A field migrated to a nested block in Storyblok.

    Imagine you want to create a component in Storyblok to define your site’s rich text so that all post types using it have the same style and options.

    For that, you can use the object format and specify the name of the field in the Storyblok model under the field property, the name of the component you want to store inside that field, and the name of the field inside the component where the content will be migrated.

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   // ... Secrets   content_types: [     {       // ... Post type WP:Storyblok       schema_mapping: {         "title": "name", // "Field in WP": "Field in Storyblok"         "_links.wp:featuredmedia.0": "content.preview_image", // Using the dot notation you can define subproperties.         // Using nested blocks in Storyblok         "content": {           field: 'content.body_items', // Field name in Storyblok           component: "rich-text", // Component name inside the above field           component_field: "content" // Field name inside the component where you want to migrate the content         }       }     }   ] })  wp2storyblok.migrate()

Entry Type Page

Now that you know how to define the field types, for the page schema, it would look like in the code block below.

The plugin will take care of the parent-child relationship between pages by creating a folder in Storyblok under the parent’s slug and associating the parent as the home of that folder.

Furthermore, if the content field contains images, the plugin will also migrate it for you!

{   name: 'pages', // Name of the post type in WP   new_content_type: 'page', // Name of the Content Type in Storyblok   schema_mapping: {     "date": "first_published_at",     "title": "name",     "slug": "slug",     "_links.wp:featuredmedia.0": "content.featured_image",     "content": "content.content",   } }

Entry Type Post

Posts have a schema similar to pages but, in this case, to store them in a folder you must define the name of the folder below the entry type:

{   name: 'posts', // Post type name in WP   new_content_type: 'post', // Content Type name in Storyblok   folder: 'articles', // Destination folder name in Storyblok   schema_mapping: {     "date": "first_published_at",     "title": "name",     "slug": "slug",     "_links.wp:featuredmedia.0": "content.featured_image",     "excerpt": "content.excerpt",     "content": "content.content",   } }
Entry Type Category

And once the schema for posts has been defined, it makes sense to define the schema for the categories so that they can be associated as described in the previous section.

In order to define the folder that contains them as categories and not as category, their default name, you must go to the Permalinks option in the WordPress admin and change the Categories base option to categories. Then the multi-option field of the Post entries will be the one that has the relationship with the corresponding categories.

Note: These steps are the same as those to be followed for migrating authors and linking them to articles.

{   name: 'categories', // Name of the post type in WP   new_content_type: 'category', // Name of the Content Type in Storyblok   // By default will be contained by a folder called Category (change it in the Permalinks option in WP)   schema_mapping: {     "name": "name",     "slug": "slug",     "description": "content.description",     "parent": "content.parent",   } }

Full Final Script

The code below will be the resulting migration script from a WP project with the basic types to the Storyblok space we had created.

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   token: '',   space_id: 34234,   content_types: [     {       name: 'pages', // Name of the post type in WP       new_content_type: 'page', // Name of the Content Type in Storyblok       schema_mapping: {         "date": "first_published_at",         "title": "name",         "slug": "slug",         "_links.wp:featuredmedia.0": "content.featured_image",         "content": "content.content",       }     },     {       name: 'categories', // Name of the post type in WP       new_content_type: 'category', // Name of the Content Type in Storyblok       // By default will be contained by a folder called Category (change it in the Permalinks option in WP)       schema_mapping: {         "name": "name",         "slug": "slug",         "description": "content.description",         "parent": "content.parent",       }     },     // Add authors as categories.     {       name: 'posts', // Name of the post type in WP       new_content_type: 'post', // Name of the Content Type in Storyblok       folder: 'articles', // Name of the destination folder in Storyblok       schema_mapping: {         "date": "first_published_at",         "title": "name",         "slug": "slug",         "_links.wp:featuredmedia.0": "content.featured_image",         "excerpt": "content.excerpt",         "content": "content.content",       }     }     // More schemas...   ] })  wp2storyblok.migrate()

4. Create A Front-End Project

Now that the content is already stored in the Storyblok dashboard, it’s time to connect the Front-end project to Storyblok.

Whatever your framework or JS library, Storyblok provides the JavaScript client that will help you with the integration. In addition, in case you are using a specific framework, you will find other packages that will ease the way, like in Nuxt the storyblok-nuxt module.

This JavaScript API will also include a bridge between Storyblok and your Front-end application. The bridge is responsible for communicating via iframe with Storyblok to tell the editing interface which component to open when the user clicks on it.

Here is a list of tutorials you can find on Storyblok to connect your Front-end project.

Note: If you don’t find your technology among them, don’t worry there are many other tutorials on the Storyblok website, search for yours in the search engine, and if you don’t find one I encourage you to contact them, and you will help many more people!

5. Host Your Front-End Project And Automate Deploy

Once your project is ready to go into production, you choose a hosting provider and link your repository for easy deployment, then you ask yourself:

How do I redeploy my static site if I publish an entry on Storyblok?

The answer is very simple: by using the webhooks offered by Storyblok and the build hooks of your hosting.

To give you a real example, you can create build hooks URLs in Netlify within the deployment section; the URL created for Storyblok in the build hooks will go in the Settings → Webhooks → Story published & unpublished field in the Storyblok space.

Guides And Tools We Have Used During Migration

Let’s recap the links that have helped in the migration of the content and those that helped to understand the functioning of the REST API and the headless CMS to which you are migrating.

WP REST API Documentation Needed

REST API
Schemas

Migrating To Storyblok

General Info
Documentation
Global Components
SEO Related
Webhooks And Build Hooks
Scripts And Packages

Jamstack

Conclusion

After reading this article you will have what you need to understand why a headless setup will improve your project, how to migrate from your WordPress project to a headless CMS like Storyblok and how to keep improving and extending your project.

As you have seen, the possibilities of a headless setup are endless. After the migration, you will have enormous flexibility to scale your project, improve its performance and SEO, increase the productivity of the development team and stay on top of the latest trends.

Everyone is starting to migrate and there is more and more content and scripts that make it easier. What are you waiting for to migrate your WordPress?

Articles on Smashing Magazine — For Web Designers And Developers

20 Jul

How To Migrate From WordPress To A Headless CMS

by TBSCategories: News

WordPress is the most used website builder in the world; almost half of the web has used WordPress to create their website. It makes sense, because it allows you to quickly create websites and has a rich plugin’s ecosystem to help you scale your site.

But technology is evolving, and there are more and more options that make it easier to create websites. Moreover, they give us the possibility to improve the website’s performance and to have more control and security over the application.

The initial WordPress architecture is monolithic, so the user interface and data access are combined on the same platform.

Since the introduction of the REST API on WordPress, it can be used in a headless way, allowing developers to use it as a backend and having the front-end in a different project.

In this decoupled way, models and controllers are bundled on the WordPress side, handling data manipulation and database interaction. Meanwhile, the front-end only interacts with the REST API via an HTTP client.

But this also has some disadvantages, you still need to configure and update WordPress, make it secure and are dependent on their technology for the development of new functionalities.

Related Reading on SmashingMag

For those of you who are just starting in the headless world, these articles will help you understand the ins and outs behind it and why everyone is starting to migrate.

But Why Migrate To A Headless CMS?

Taking into account that this article will showcase how to migrate from WordPress to a Headless CMS, WordPress is probably your current setup.

A Headless CMS will give us the freedom to focus only on the front-end project, being able to choose the technology we are familiar with, and on the structure of our data. In the end, it takes care of the content management and the content delivery, so that we can take care of the rendering part.

“A Headless CMS is a system that provides the same features as a Content Management System (CMS) and more, all exposed through an API.”

This type of setup is especially useful for companies that have multiple sites and want to reduce costs or simplify processes. A headless architecture allows these companies to centralize content management in a single administration interface, providing the APIs that will be consumed by the company’s different web pages.

Another common use of a headless architecture is to create a front-end project that represents the company brand. In this way, all the products that the company launches will have the same look and feel, but each one will have its own content, managed in the same administration panel.

Note: This example can be easily seen on conference websites such as JSWorld Conference and VueJS Amsterdam which, being from the same creators, the front-end project is the same, only the content changes.

Different to a CMS like WordPress, in a Headless CMS you have an administration panel already configured and maintained, and sometimes also hosted, for you. To start creating content, you just need to create an account, log in, and you will be able to create, edit, duplicate and delete your content, manage users, translate content and work with publication workflows, among other things.

A headless CMS will make it easier for the people in your team to understand the workflow, whether they are content creators or marketers, something to keep in mind if you aren’t the only one who will edit the content.

It is worth noting that some Headless CMS, not only focuses on offering you the services already offered by a CMS like WordPress. It also provides services such as image CDNs to resize or reformat your images on the fly, or additional security through S3 backups.

Having this setup will not only give you freedom, security and comfort, but will also improve the performance of your application without third-party services. Just by connecting your front-end project via an HTTP client and getting the components and data, you will be up and running.

The Benefits Of Going Headless And When It Makes Sense

WordPress’ architecture often does not offer the possibilities we sometimes need when working on a website, especially when it comes to optimizing performance, one of the most important points when ranking our site in a search engine like Google and especially now that Web Vitals is up and running.

But it is clear that if we have a personal site that only we ourselves work on, then it’s not necessary to migrate it to a headless setup. However, if more people are involved in that project (not just developers but content creators or marketing teams), then we should consider adopting Headless CMS.

How Can A Headless CMS Help Us Improve The Performance Of Our Website And The Quality Of Our Front-End Project?

  • By allowing you to develop the front-end in a way that is completely independent of the platform where you edit your content.

    The technology you choose is your own choice, if you wanted to upgrade your project to the latest front-end framework, you would not be dependent on a back-end and could do so without having to rethink migrations.

  • Allowing you to create multiplatform projects without having to depend on different administration panels.

    In the end, if for an app you need a shorter description than the main website, you can always make use of a new “short_description” field and just represent it on the front-end of that specific app.

  • It is intended to make development easier and simplify the process of creating a site, as well as scaling it.

    By having the front-end completely isolated we can change the visual appearance of our entire application without modifying the structure of our content.

  • Always offering services that will allow us to optimize our assets and the speed of response with which they are served to us. Ultimately all our data will be delivered through CDN networks.

A content delivery network (CDN), is a geographically distributed network of proxy servers and their data centers. The goal is to provide high availability and performance by distributing the service spatially relative to end-users.

What If We Are Concerned About How It Will Work With Our Brand’s Or Company’s Structure?

  • As well as supporting cross-platform applications, it also allows us to maintain brand consistency.

    Having the front-end as a base project and having multiples spaces in a Headless CMS, allows you to have consistency between your products and makes the scalability easier because we have less code to maintain.

  • Although not all headless CMS have this benefit, the headless CMS we are migrating to, Storyblok, has a Visual Editor, which allows creating independence among teams. The editors or content creators can access the panel to edit existing content or create new content, being able to see a preview of how it will look before publishing. So they won’t have to involve the development team in this process and can do their work more efficiently.
  • It also streamlines content management by allowing you to set up your own content workflow. You can define the stages that a piece of content must go through before being published and, only when it passes the process successfully, it will be published.

How Can A Headless CMS Save Time Compared To A Traditional CMS?

  • Taking care of maintaining the security of the platform and updating it on your behalf. Whenever there is a bug or users require a new feature, the team behind your Headless CMS will develop it for you, you just have to start using it!
  • Constantly improving the user experience (UX) and design (UI) for you, so that content creators and developers feel comfortable creating new fields, components or pages. But not only on the visual aspect, but they will also be looking to improve the performance of the database, so you get your content instantly and forget about all the work that is involved.
Monolithic vs Headless
Feature Monolithic Headless
Architecture Coupled: linked back-end front-end Decoupled: independent front-end project
Technology You will have to use the one in which the project is developed Freedom to choose your front-end technology
Cross-platform Limited to one front-end at a time Connects to any front-end projects
Content workflow Restrictive Custom
Security and updates You take care It takes care for you

Having seen the advantages that a headless setup can bring to our project and the people who work on it, I think it is time to look at the steps we need to migrate our project.

What You Need To Keep In Mind When Going Headless

As we have already mentioned, Headless CMS allow for a clean separation of concerns between content creators and developers. In this way (in a Headless CMS), the developer focuses on creating the content structure, which will be represented in the front-end project, and the editor will be in charge of using the components and filling them with content in the admin panel.

Type Of Content We Can Create In A Headless CMS

1. Types of entry or template

Similar to Custom Post Types in WordPress but with more freedom and extensibility when it comes to data types and editors.

When you go to create a new content entry in your dashboard, you expect to be able to choose what type it depends on the situation. For example, if you have a website with a blog you will want to have several types of templates, one for pages with listings or dynamic content called “page” and one for each blog entry “post“.

Depending on the headless CMS you have chosen, the name will vary but the concept is the same. In Storyblok these types of entities are called Content Type. “Content Types” define the type of content entry and can hold the basic fields for your content entries. By default, we have a “Page” content type.

2. Reusable components

In a Headless CMS, you can create, in addition to Content Types, nested components and reuse them between content types and other components. In Storyblok, this type of component — as you may have noticed from its name — is called Blok.

To use them in a Content Type such as a page, you will need to create a field in the schema of type blocks. This field allows you to add nested components to your page while adding content.

But, in principle, we will not need such components during the migration. It simply gives you the flexibility to create robust and dynamic applications without having to involve the developer.

For example, when a member of the marketing team wants to add a new Hero to the About us page, if the Hero component was created as nested and the page had a Blocks field, the marketing person could add the Hero without having to involve the developer.

Rendering The Data Coming From The Headless CMS

As we are defining the structure of our content in the Headless CMS panel, we have to consider which framework we want to create our front-end project with and which HTTP client we will use.

When choosing a framework we have to take several factors into account:

Are my team and I am familiar with this technology?

Does it allow me to render my content in the type of rendering my project needs?

Does it have plugins or modules that facilitate integration with the Headless CMS I’m using?

In most cases, a static site will be sufficient and will always be the most economical and high-performance answer. So, you just have to look for a static site generator for the technology you are familiar with, for example, Nuxt for Vue or Next for the React library.

Connecting these two things, a Headless CMS and a static site builder are considered as a set of web development best practices focused on providing the highest performance, security and lowest cost. This architecture is also known as Jamstack. It’s an architecture designed to make the web faster, more secure and easier to scale. It builds on many of the tools and workflows which developers love, and which bring maximum productivity.

By making use of the trendy frameworks, you will be assured of an integration guide with the Headless CMS you are going to work with, and most of them have already a module or package that allows you to obtain information from the API and in many cases extend it.

The only thing left for you to do is to define the structure of your components concerning how you have structured the data in your Headless CMS and automate the content publishing process. For example, using the Webhooks that the Headless CMS provides you with, you will be able to start a build process in your favourite hosting by its build hooks once the content has been published.

Amount Of Time You’ll Need

As with any migration, the time required will always depend proportionally on the complexity of your project. If we are talking about a common WordPress site you will only need to migrate the Post types that you have defined or that comes by default in it, such as Pages, Posts and Categories, and their content.

If, on the other hand, you have customized your project with multiple plugins, you will have to develop them through the front-end project or using the ones provided by your Headless CMS. For example, if we are SEO conscious and therefore make use of Yoast SEO on WordPress, we will have the Field-Type SEO plugin in Storyblok to help us in the transition, but we will still have to develop our sitemap in the front-end with a guide to help us.

In the end, all the burden of development will fall on the front-end project, as setting up the Headless CMS will not take that much time.

But let’s stop talking and let’s take a look at it!

Steps To Migrate Our Content From WordPress To Storyblok

The migration will consist of four steps, from the creation of a space in our new Headless CMS Storyblok to the representation of the migrated content in our front-end project, which we will see in detail below and in which I will leave you resources to make the migration easier for you.

Let’s get started!

1. Creating A Space In Storyblok

In order to create a space in Storyblok, you first need to have an account. To do this, you will need to select the plan that suits you best.

Go to the Pricing page and start with the plan that best suits your needs or try the free plan for testing.

Create your account, and you will be able to access the panel.

Choose ‘Create a new space’ and let’s get started!

Space is a content repository. Think of it as a place to keep all the content related to one project. Each space has its own components, data sources, assets, environments, domains, collaborators and permissions.

Take some time to explore the sections on the left sidebar. Start by browsing the following:

  • Content, this will be the folder where the content will be stored, where the marketing team will spend most of their time.
  • Assets, where all the images will be stored, which you can then get through the CDN service, optimized and of any size.
  • Components, where you will create the Content types and Nested components.
  • Settings, the section where you will be able to configure the data of your space as well as the languages of your application, the workflows you want your content to follow before being published, user permissions, etc. Let’s say that this area will be the one related to the IT team of the project.

If you still want to explore every option on the dashboard before diving into the migration, I recommend taking a look at Understanding the UI by Storyblok.

Now that you know a bit about the Storyblok ecosystem, it’s time to define what the content of our application will look like.

2. Defining Models

To migrate WordPress content to Storyblok, the next step is to create the schemas that define the WP data structure by creating Post Types in the Storyblok space.

Let’s start with pages and posts (the main Post Types in any WP site), which we’ll call page and post in Storyblok.

The schema of pages in WP contains the fields: title, slug, featured image, date, and content.

Note: To see all the fields contained in a Post Type go to the schema at WP REST API schema references.

What you need to know is that, by default, any Content Type in Storyblok will have some fields already defined for you, such as Name, Slug, Tags, First published date, and so on.

Those fields could be used to migrate the content from WP. You will only need to extend it by adding featured_image and content in the Page Content Type.

Go to the Components section in your space, click on the page created by default, remove the body field and add featured_image as type Assets > Images and content as Rich-text.

Once the page schema is ready, let’s move on to the post. For the Post Content Type, it is necessary to include more information, such as featured_image, excerpt, content, and relationships to other types such as Authors or Categories.

Since Authors and Categories will also have their own content, go to the Content section in the sidebar and create a couple of folders called authors and categories.

Each of the folders must have a default Content Type associated. To do this, in the Components section, create Author and Category as new Content Types, and then associate the Content Type relative to each folder by clicking on the three dots on the right of the folder and selecting Settings.

In this way, in the Post Content Type you can add a Single-Option or Multi-Options field with source Stories and point to the folder created for each field:

  • Authors
    This specifies the folder where they are located authors/.
  • Categories
    This specifies the folder where they are located categories/.

Note: If you want to know more about this relationship, have a look at the article Authors and Articles Relationship.

Now that you have seen how to create a couple of Content Types and how to create relationships between them, you will have to define the rest of the models following the same steps.

Adding A Content Type: Global

And you ask yourself, what about the content that all my pages will share? Like the navigation menu, footer, and other common elements?

Don’t worry, Storyblok has already thought about that and offers us a simple guide to define our global elements dynamically. It shows us how to create a global Content Type and how to use it in the Content section.

3. Migrating The Content

Now it’s time to start migrating the content you have stored. To access WP content you need to access the REST JSON API. Access the path /wp-json, if the project is deployed, or ?rest_route=/ if local.

In case neither of the two routes works, inspect the HTML of your page for a link in the head with rel="https://api.w.org/", as indicated in the WP discovery guide, and get the correct one.

To help us during the migration, the Storyblok developers have provided us with a plugin that will save us a lot of work. This plugin is called wordpress-importer, on it, it is possible to define the equivalent Content Type in Storyblok for the WP Post type to be migrated, and it will push it to our space and migrate the images to our Assets section for us.

Note: Using this script requires node ≥14.0.0 because it’s using optional chaining.

Creating The Migration Script

The first thing to do is to clone the repository. Then, install the NPM packages, using npm install or yarn, and create a file in the root of the project as migrateWPtoStoryblok.js. In order to run the script you need a script in package.json to run it, add:

"migrate": "node ./migrateWPtoStoryblok.js"

Once everything is ready, it’s time to start defining the script following the README specifications. And, as you can see, the next thing that will be needed is to find the Space_id and the OAuth token to connect to the Storyblok space.

  • The Space_id is in the Settings section of the sidebar, as soon as you click on it, you will see it on the right side.
  • To generate the OAuth token, you need to go to the top of the sidebar, click on the little arrow right next to the Storyblok logo, and go to My Account. If we scroll down we will see the Personal access tokens section, generate one, and copy it.

When you have obtained both secrets, you can add them to the beginning of the script along with the URL of the JSON API of your project:

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   token: 'storyblok-oauth-token', // My Account > Personal access tokens   space_id: 'space-id', // Settings })

As described in previous sections, the Page Content Type in Storyblok is the equivalent of the Post Type in WP pages. In the code block below, you’ll see where you’ll need to specify each.

And, once the Post Type and Content Type are defined, it is time to specify the name of the fields used in this entity type in WP and the equivalent name in Storyblok, in the schema_mapping option.

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   // ... Secrets   content_types: [     {       name: 'pages', // Post type in WP       new_content_type: 'page', // Equivalent Content type in Storyblok       folder: '', // OPTIONAL: To save all the content of the same type in a specific folder       schema_mapping: {         "title": "name", // "Field in WP": "Field in Storyblok"       }     }   ] })

Note: For the migration to work correctly, make sure that the permalinks are selected by the name of the entry and not as simple. Otherwise, the script will not create the parent-child relationship between pages.

Within the schema_mapping you can define several types of fields, these can be:

  • A simple field, such as title.
  • A sub-property of a field, like in this case the URL of the feature image.
    Note: The plugin itself takes care of migrating the images to the Storyblok space via the associated URL in links.wp:featuredmedia.0.

  • A field migrated to a nested block in Storyblok.

    Imagine you want to create a component in Storyblok to define your site’s rich text so that all post types using it have the same style and options.

    For that, you can use the object format and specify the name of the field in the Storyblok model under the field property, the name of the component you want to store inside that field, and the name of the field inside the component where the content will be migrated.

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   // ... Secrets   content_types: [     {       // ... Post type WP:Storyblok       schema_mapping: {         "title": "name", // "Field in WP": "Field in Storyblok"         "_links.wp:featuredmedia.0": "content.preview_image", // Using the dot notation you can define subproperties.         // Using nested blocks in Storyblok         "content": {           field: 'content.body_items', // Field name in Storyblok           component: "rich-text", // Component name inside the above field           component_field: "content" // Field name inside the component where you want to migrate the content         }       }     }   ] })  wp2storyblok.migrate()

Entry Type Page

Now that you know how to define the field types, for the page schema, it would look like in the code block below.

The plugin will take care of the parent-child relationship between pages by creating a folder in Storyblok under the parent’s slug and associating the parent as the home of that folder.

Furthermore, if the content field contains images, the plugin will also migrate it for you!

{   name: 'pages', // Name of the post type in WP   new_content_type: 'page', // Name of the Content Type in Storyblok   schema_mapping: {     "date": "first_published_at",     "title": "name",     "slug": "slug",     "_links.wp:featuredmedia.0": "content.featured_image",     "content": "content.content",   } }

Entry Type Post

Posts have a schema similar to pages but, in this case, to store them in a folder you must define the name of the folder below the entry type:

{   name: 'posts', // Post type name in WP   new_content_type: 'post', // Content Type name in Storyblok   folder: 'articles', // Destination folder name in Storyblok   schema_mapping: {     "date": "first_published_at",     "title": "name",     "slug": "slug",     "_links.wp:featuredmedia.0": "content.featured_image",     "excerpt": "content.excerpt",     "content": "content.content",   } }
Entry Type Category

And once the schema for posts has been defined, it makes sense to define the schema for the categories so that they can be associated as described in the previous section.

In order to define the folder that contains them as categories and not as category, their default name, you must go to the Permalinks option in the WordPress admin and change the Categories base option to categories. Then the multi-option field of the Post entries will be the one that has the relationship with the corresponding categories.

Note: These steps are the same as those to be followed for migrating authors and linking them to articles.

{   name: 'categories', // Name of the post type in WP   new_content_type: 'category', // Name of the Content Type in Storyblok   // By default will be contained by a folder called Category (change it in the Permalinks option in WP)   schema_mapping: {     "name": "name",     "slug": "slug",     "description": "content.description",     "parent": "content.parent",   } }

Full Final Script

The code below will be the resulting migration script from a WP project with the basic types to the Storyblok space we had created.

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   token: '',   space_id: 34234,   content_types: [     {       name: 'pages', // Name of the post type in WP       new_content_type: 'page', // Name of the Content Type in Storyblok       schema_mapping: {         "date": "first_published_at",         "title": "name",         "slug": "slug",         "_links.wp:featuredmedia.0": "content.featured_image",         "content": "content.content",       }     },     {       name: 'categories', // Name of the post type in WP       new_content_type: 'category', // Name of the Content Type in Storyblok       // By default will be contained by a folder called Category (change it in the Permalinks option in WP)       schema_mapping: {         "name": "name",         "slug": "slug",         "description": "content.description",         "parent": "content.parent",       }     },     // Add authors as categories.     {       name: 'posts', // Name of the post type in WP       new_content_type: 'post', // Name of the Content Type in Storyblok       folder: 'articles', // Name of the destination folder in Storyblok       schema_mapping: {         "date": "first_published_at",         "title": "name",         "slug": "slug",         "_links.wp:featuredmedia.0": "content.featured_image",         "excerpt": "content.excerpt",         "content": "content.content",       }     }     // More schemas...   ] })  wp2storyblok.migrate()

4. Create A Front-End Project

Now that the content is already stored in the Storyblok dashboard, it’s time to connect the Front-end project to Storyblok.

Whatever your framework or JS library, Storyblok provides the JavaScript client that will help you with the integration. In addition, in case you are using a specific framework, you will find other packages that will ease the way, like in Nuxt the storyblok-nuxt module.

This JavaScript API will also include a bridge between Storyblok and your Front-end application. The bridge is responsible for communicating via iframe with Storyblok to tell the editing interface which component to open when the user clicks on it.

Here is a list of tutorials you can find on Storyblok to connect your Front-end project.

Note: If you don’t find your technology among them, don’t worry there are many other tutorials on the Storyblok website, search for yours in the search engine, and if you don’t find one I encourage you to contact them, and you will help many more people!

5. Host Your Front-End Project And Automate Deploy

Once your project is ready to go into production, you choose a hosting provider and link your repository for easy deployment, then you ask yourself:

How do I redeploy my static site if I publish an entry on Storyblok?

The answer is very simple: by using the webhooks offered by Storyblok and the build hooks of your hosting.

To give you a real example, you can create build hooks URLs in Netlify within the deployment section; the URL created for Storyblok in the build hooks will go in the Settings → Webhooks → Story published & unpublished field in the Storyblok space.

Guides And Tools We Have Used During Migration

Let’s recap the links that have helped in the migration of the content and those that helped to understand the functioning of the REST API and the headless CMS to which you are migrating.

WP REST API Documentation Needed

REST API
Schemas

Migrating To Storyblok

General Info
Documentation
Global Components
SEO Related
Webhooks And Build Hooks
Scripts And Packages

Jamstack

Conclusion

After reading this article you will have what you need to understand why a headless setup will improve your project, how to migrate from your WordPress project to a headless CMS like Storyblok and how to keep improving and extending your project.

As you have seen, the possibilities of a headless setup are endless. After the migration, you will have enormous flexibility to scale your project, improve its performance and SEO, increase the productivity of the development team and stay on top of the latest trends.

Everyone is starting to migrate and there is more and more content and scripts that make it easier. What are you waiting for to migrate your WordPress?

Articles on Smashing Magazine — For Web Designers And Developers

20 Jul

How To Migrate From WordPress To A Headless CMS

by TBSCategories: News

WordPress is the most used website builder in the world; almost half of the web has used WordPress to create their website. It makes sense, because it allows you to quickly create websites and has a rich plugin’s ecosystem to help you scale your site.

But technology is evolving, and there are more and more options that make it easier to create websites. Moreover, they give us the possibility to improve the website’s performance and to have more control and security over the application.

The initial WordPress architecture is monolithic, so the user interface and data access are combined on the same platform.

Since the introduction of the REST API on WordPress, it can be used in a headless way, allowing developers to use it as a backend and having the front-end in a different project.

In this decoupled way, models and controllers are bundled on the WordPress side, handling data manipulation and database interaction. Meanwhile, the front-end only interacts with the REST API via an HTTP client.

But this also has some disadvantages, you still need to configure and update WordPress, make it secure and are dependent on their technology for the development of new functionalities.

Related Reading on SmashingMag

For those of you who are just starting in the headless world, these articles will help you understand the ins and outs behind it and why everyone is starting to migrate.

But Why Migrate To A Headless CMS?

Taking into account that this article will showcase how to migrate from WordPress to a Headless CMS, WordPress is probably your current setup.

A Headless CMS will give us the freedom to focus only on the front-end project, being able to choose the technology we are familiar with, and on the structure of our data. In the end, it takes care of the content management and the content delivery, so that we can take care of the rendering part.

“A Headless CMS is a system that provides the same features as a Content Management System (CMS) and more, all exposed through an API.”

This type of setup is especially useful for companies that have multiple sites and want to reduce costs or simplify processes. A headless architecture allows these companies to centralize content management in a single administration interface, providing the APIs that will be consumed by the company’s different web pages.

Another common use of a headless architecture is to create a front-end project that represents the company brand. In this way, all the products that the company launches will have the same look and feel, but each one will have its own content, managed in the same administration panel.

Note: This example can be easily seen on conference websites such as JSWorld Conference and VueJS Amsterdam which, being from the same creators, the front-end project is the same, only the content changes.

Different to a CMS like WordPress, in a Headless CMS you have an administration panel already configured and maintained, and sometimes also hosted, for you. To start creating content, you just need to create an account, log in, and you will be able to create, edit, duplicate and delete your content, manage users, translate content and work with publication workflows, among other things.

A headless CMS will make it easier for the people in your team to understand the workflow, whether they are content creators or marketers, something to keep in mind if you aren’t the only one who will edit the content.

It is worth noting that some Headless CMS, not only focuses on offering you the services already offered by a CMS like WordPress. It also provides services such as image CDNs to resize or reformat your images on the fly, or additional security through S3 backups.

Having this setup will not only give you freedom, security and comfort, but will also improve the performance of your application without third-party services. Just by connecting your front-end project via an HTTP client and getting the components and data, you will be up and running.

The Benefits Of Going Headless And When It Makes Sense

WordPress’ architecture often does not offer the possibilities we sometimes need when working on a website, especially when it comes to optimizing performance, one of the most important points when ranking our site in a search engine like Google and especially now that Web Vitals is up and running.

But it is clear that if we have a personal site that only we ourselves work on, then it’s not necessary to migrate it to a headless setup. However, if more people are involved in that project (not just developers but content creators or marketing teams), then we should consider adopting Headless CMS.

How Can A Headless CMS Help Us Improve The Performance Of Our Website And The Quality Of Our Front-End Project?

  • By allowing you to develop the front-end in a way that is completely independent of the platform where you edit your content.

    The technology you choose is your own choice, if you wanted to upgrade your project to the latest front-end framework, you would not be dependent on a back-end and could do so without having to rethink migrations.

  • Allowing you to create multiplatform projects without having to depend on different administration panels.

    In the end, if for an app you need a shorter description than the main website, you can always make use of a new “short_description” field and just represent it on the front-end of that specific app.

  • It is intended to make development easier and simplify the process of creating a site, as well as scaling it.

    By having the front-end completely isolated we can change the visual appearance of our entire application without modifying the structure of our content.

  • Always offering services that will allow us to optimize our assets and the speed of response with which they are served to us. Ultimately all our data will be delivered through CDN networks.

A content delivery network (CDN), is a geographically distributed network of proxy servers and their data centers. The goal is to provide high availability and performance by distributing the service spatially relative to end-users.

What If We Are Concerned About How It Will Work With Our Brand’s Or Company’s Structure?

  • As well as supporting cross-platform applications, it also allows us to maintain brand consistency.

    Having the front-end as a base project and having multiples spaces in a Headless CMS, allows you to have consistency between your products and makes the scalability easier because we have less code to maintain.

  • Although not all headless CMS have this benefit, the headless CMS we are migrating to, Storyblok, has a Visual Editor, which allows creating independence among teams. The editors or content creators can access the panel to edit existing content or create new content, being able to see a preview of how it will look before publishing. So they won’t have to involve the development team in this process and can do their work more efficiently.
  • It also streamlines content management by allowing you to set up your own content workflow. You can define the stages that a piece of content must go through before being published and, only when it passes the process successfully, it will be published.

How Can A Headless CMS Save Time Compared To A Traditional CMS?

  • Taking care of maintaining the security of the platform and updating it on your behalf. Whenever there is a bug or users require a new feature, the team behind your Headless CMS will develop it for you, you just have to start using it!
  • Constantly improving the user experience (UX) and design (UI) for you, so that content creators and developers feel comfortable creating new fields, components or pages. But not only on the visual aspect, but they will also be looking to improve the performance of the database, so you get your content instantly and forget about all the work that is involved.
Monolithic vs Headless
Feature Monolithic Headless
Architecture Coupled: linked back-end front-end Decoupled: independent front-end project
Technology You will have to use the one in which the project is developed Freedom to choose your front-end technology
Cross-platform Limited to one front-end at a time Connects to any front-end projects
Content workflow Restrictive Custom
Security and updates You take care It takes care for you

Having seen the advantages that a headless setup can bring to our project and the people who work on it, I think it is time to look at the steps we need to migrate our project.

What You Need To Keep In Mind When Going Headless

As we have already mentioned, Headless CMS allow for a clean separation of concerns between content creators and developers. In this way (in a Headless CMS), the developer focuses on creating the content structure, which will be represented in the front-end project, and the editor will be in charge of using the components and filling them with content in the admin panel.

Type Of Content We Can Create In A Headless CMS

1. Types of entry or template

Similar to Custom Post Types in WordPress but with more freedom and extensibility when it comes to data types and editors.

When you go to create a new content entry in your dashboard, you expect to be able to choose what type it depends on the situation. For example, if you have a website with a blog you will want to have several types of templates, one for pages with listings or dynamic content called “page” and one for each blog entry “post“.

Depending on the headless CMS you have chosen, the name will vary but the concept is the same. In Storyblok these types of entities are called Content Type. “Content Types” define the type of content entry and can hold the basic fields for your content entries. By default, we have a “Page” content type.

2. Reusable components

In a Headless CMS, you can create, in addition to Content Types, nested components and reuse them between content types and other components. In Storyblok, this type of component — as you may have noticed from its name — is called Blok.

To use them in a Content Type such as a page, you will need to create a field in the schema of type blocks. This field allows you to add nested components to your page while adding content.

But, in principle, we will not need such components during the migration. It simply gives you the flexibility to create robust and dynamic applications without having to involve the developer.

For example, when a member of the marketing team wants to add a new Hero to the About us page, if the Hero component was created as nested and the page had a Blocks field, the marketing person could add the Hero without having to involve the developer.

Rendering The Data Coming From The Headless CMS

As we are defining the structure of our content in the Headless CMS panel, we have to consider which framework we want to create our front-end project with and which HTTP client we will use.

When choosing a framework we have to take several factors into account:

Are my team and I am familiar with this technology?

Does it allow me to render my content in the type of rendering my project needs?

Does it have plugins or modules that facilitate integration with the Headless CMS I’m using?

In most cases, a static site will be sufficient and will always be the most economical and high-performance answer. So, you just have to look for a static site generator for the technology you are familiar with, for example, Nuxt for Vue or Next for the React library.

Connecting these two things, a Headless CMS and a static site builder are considered as a set of web development best practices focused on providing the highest performance, security and lowest cost. This architecture is also known as Jamstack. It’s an architecture designed to make the web faster, more secure and easier to scale. It builds on many of the tools and workflows which developers love, and which bring maximum productivity.

By making use of the trendy frameworks, you will be assured of an integration guide with the Headless CMS you are going to work with, and most of them have already a module or package that allows you to obtain information from the API and in many cases extend it.

The only thing left for you to do is to define the structure of your components concerning how you have structured the data in your Headless CMS and automate the content publishing process. For example, using the Webhooks that the Headless CMS provides you with, you will be able to start a build process in your favourite hosting by its build hooks once the content has been published.

Amount Of Time You’ll Need

As with any migration, the time required will always depend proportionally on the complexity of your project. If we are talking about a common WordPress site you will only need to migrate the Post types that you have defined or that comes by default in it, such as Pages, Posts and Categories, and their content.

If, on the other hand, you have customized your project with multiple plugins, you will have to develop them through the front-end project or using the ones provided by your Headless CMS. For example, if we are SEO conscious and therefore make use of Yoast SEO on WordPress, we will have the Field-Type SEO plugin in Storyblok to help us in the transition, but we will still have to develop our sitemap in the front-end with a guide to help us.

In the end, all the burden of development will fall on the front-end project, as setting up the Headless CMS will not take that much time.

But let’s stop talking and let’s take a look at it!

Steps To Migrate Our Content From WordPress To Storyblok

The migration will consist of four steps, from the creation of a space in our new Headless CMS Storyblok to the representation of the migrated content in our front-end project, which we will see in detail below and in which I will leave you resources to make the migration easier for you.

Let’s get started!

1. Creating A Space In Storyblok

In order to create a space in Storyblok, you first need to have an account. To do this, you will need to select the plan that suits you best.

Go to the Pricing page and start with the plan that best suits your needs or try the free plan for testing.

Create your account, and you will be able to access the panel.

Choose ‘Create a new space’ and let’s get started!

Space is a content repository. Think of it as a place to keep all the content related to one project. Each space has its own components, data sources, assets, environments, domains, collaborators and permissions.

Take some time to explore the sections on the left sidebar. Start by browsing the following:

  • Content, this will be the folder where the content will be stored, where the marketing team will spend most of their time.
  • Assets, where all the images will be stored, which you can then get through the CDN service, optimized and of any size.
  • Components, where you will create the Content types and Nested components.
  • Settings, the section where you will be able to configure the data of your space as well as the languages of your application, the workflows you want your content to follow before being published, user permissions, etc. Let’s say that this area will be the one related to the IT team of the project.

If you still want to explore every option on the dashboard before diving into the migration, I recommend taking a look at Understanding the UI by Storyblok.

Now that you know a bit about the Storyblok ecosystem, it’s time to define what the content of our application will look like.

2. Defining Models

To migrate WordPress content to Storyblok, the next step is to create the schemas that define the WP data structure by creating Post Types in the Storyblok space.

Let’s start with pages and posts (the main Post Types in any WP site), which we’ll call page and post in Storyblok.

The schema of pages in WP contains the fields: title, slug, featured image, date, and content.

Note: To see all the fields contained in a Post Type go to the schema at WP REST API schema references.

What you need to know is that, by default, any Content Type in Storyblok will have some fields already defined for you, such as Name, Slug, Tags, First published date, and so on.

Those fields could be used to migrate the content from WP. You will only need to extend it by adding featured_image and content in the Page Content Type.

Go to the Components section in your space, click on the page created by default, remove the body field and add featured_image as type Assets > Images and content as Rich-text.

Once the page schema is ready, let’s move on to the post. For the Post Content Type, it is necessary to include more information, such as featured_image, excerpt, content, and relationships to other types such as Authors or Categories.

Since Authors and Categories will also have their own content, go to the Content section in the sidebar and create a couple of folders called authors and categories.

Each of the folders must have a default Content Type associated. To do this, in the Components section, create Author and Category as new Content Types, and then associate the Content Type relative to each folder by clicking on the three dots on the right of the folder and selecting Settings.

In this way, in the Post Content Type you can add a Single-Option or Multi-Options field with source Stories and point to the folder created for each field:

  • Authors
    This specifies the folder where they are located authors/.
  • Categories
    This specifies the folder where they are located categories/.

Note: If you want to know more about this relationship, have a look at the article Authors and Articles Relationship.

Now that you have seen how to create a couple of Content Types and how to create relationships between them, you will have to define the rest of the models following the same steps.

Adding A Content Type: Global

And you ask yourself, what about the content that all my pages will share? Like the navigation menu, footer, and other common elements?

Don’t worry, Storyblok has already thought about that and offers us a simple guide to define our global elements dynamically. It shows us how to create a global Content Type and how to use it in the Content section.

3. Migrating The Content

Now it’s time to start migrating the content you have stored. To access WP content you need to access the REST JSON API. Access the path /wp-json, if the project is deployed, or ?rest_route=/ if local.

In case neither of the two routes works, inspect the HTML of your page for a link in the head with rel="https://api.w.org/", as indicated in the WP discovery guide, and get the correct one.

To help us during the migration, the Storyblok developers have provided us with a plugin that will save us a lot of work. This plugin is called wordpress-importer, on it, it is possible to define the equivalent Content Type in Storyblok for the WP Post type to be migrated, and it will push it to our space and migrate the images to our Assets section for us.

Note: Using this script requires node ≥14.0.0 because it’s using optional chaining.

Creating The Migration Script

The first thing to do is to clone the repository. Then, install the NPM packages, using npm install or yarn, and create a file in the root of the project as migrateWPtoStoryblok.js. In order to run the script you need a script in package.json to run it, add:

"migrate": "node ./migrateWPtoStoryblok.js"

Once everything is ready, it’s time to start defining the script following the README specifications. And, as you can see, the next thing that will be needed is to find the Space_id and the OAuth token to connect to the Storyblok space.

  • The Space_id is in the Settings section of the sidebar, as soon as you click on it, you will see it on the right side.
  • To generate the OAuth token, you need to go to the top of the sidebar, click on the little arrow right next to the Storyblok logo, and go to My Account. If we scroll down we will see the Personal access tokens section, generate one, and copy it.

When you have obtained both secrets, you can add them to the beginning of the script along with the URL of the JSON API of your project:

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   token: 'storyblok-oauth-token', // My Account > Personal access tokens   space_id: 'space-id', // Settings })

As described in previous sections, the Page Content Type in Storyblok is the equivalent of the Post Type in WP pages. In the code block below, you’ll see where you’ll need to specify each.

And, once the Post Type and Content Type are defined, it is time to specify the name of the fields used in this entity type in WP and the equivalent name in Storyblok, in the schema_mapping option.

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   // ... Secrets   content_types: [     {       name: 'pages', // Post type in WP       new_content_type: 'page', // Equivalent Content type in Storyblok       folder: '', // OPTIONAL: To save all the content of the same type in a specific folder       schema_mapping: {         "title": "name", // "Field in WP": "Field in Storyblok"       }     }   ] })

Note: For the migration to work correctly, make sure that the permalinks are selected by the name of the entry and not as simple. Otherwise, the script will not create the parent-child relationship between pages.

Within the schema_mapping you can define several types of fields, these can be:

  • A simple field, such as title.
  • A sub-property of a field, like in this case the URL of the feature image.
    Note: The plugin itself takes care of migrating the images to the Storyblok space via the associated URL in links.wp:featuredmedia.0.

  • A field migrated to a nested block in Storyblok.

    Imagine you want to create a component in Storyblok to define your site’s rich text so that all post types using it have the same style and options.

    For that, you can use the object format and specify the name of the field in the Storyblok model under the field property, the name of the component you want to store inside that field, and the name of the field inside the component where the content will be migrated.

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   // ... Secrets   content_types: [     {       // ... Post type WP:Storyblok       schema_mapping: {         "title": "name", // "Field in WP": "Field in Storyblok"         "_links.wp:featuredmedia.0": "content.preview_image", // Using the dot notation you can define subproperties.         // Using nested blocks in Storyblok         "content": {           field: 'content.body_items', // Field name in Storyblok           component: "rich-text", // Component name inside the above field           component_field: "content" // Field name inside the component where you want to migrate the content         }       }     }   ] })  wp2storyblok.migrate()

Entry Type Page

Now that you know how to define the field types, for the page schema, it would look like in the code block below.

The plugin will take care of the parent-child relationship between pages by creating a folder in Storyblok under the parent’s slug and associating the parent as the home of that folder.

Furthermore, if the content field contains images, the plugin will also migrate it for you!

{   name: 'pages', // Name of the post type in WP   new_content_type: 'page', // Name of the Content Type in Storyblok   schema_mapping: {     "date": "first_published_at",     "title": "name",     "slug": "slug",     "_links.wp:featuredmedia.0": "content.featured_image",     "content": "content.content",   } }

Entry Type Post

Posts have a schema similar to pages but, in this case, to store them in a folder you must define the name of the folder below the entry type:

{   name: 'posts', // Post type name in WP   new_content_type: 'post', // Content Type name in Storyblok   folder: 'articles', // Destination folder name in Storyblok   schema_mapping: {     "date": "first_published_at",     "title": "name",     "slug": "slug",     "_links.wp:featuredmedia.0": "content.featured_image",     "excerpt": "content.excerpt",     "content": "content.content",   } }
Entry Type Category

And once the schema for posts has been defined, it makes sense to define the schema for the categories so that they can be associated as described in the previous section.

In order to define the folder that contains them as categories and not as category, their default name, you must go to the Permalinks option in the WordPress admin and change the Categories base option to categories. Then the multi-option field of the Post entries will be the one that has the relationship with the corresponding categories.

Note: These steps are the same as those to be followed for migrating authors and linking them to articles.

{   name: 'categories', // Name of the post type in WP   new_content_type: 'category', // Name of the Content Type in Storyblok   // By default will be contained by a folder called Category (change it in the Permalinks option in WP)   schema_mapping: {     "name": "name",     "slug": "slug",     "description": "content.description",     "parent": "content.parent",   } }

Full Final Script

The code below will be the resulting migration script from a WP project with the basic types to the Storyblok space we had created.

import { Wp2Storyblok } from './index.js'  const wp2storyblok = new Wp2Storyblok('https://your-domain.com/wp-json', {   token: '',   space_id: 34234,   content_types: [     {       name: 'pages', // Name of the post type in WP       new_content_type: 'page', // Name of the Content Type in Storyblok       schema_mapping: {         "date": "first_published_at",         "title": "name",         "slug": "slug",         "_links.wp:featuredmedia.0": "content.featured_image",         "content": "content.content",       }     },     {       name: 'categories', // Name of the post type in WP       new_content_type: 'category', // Name of the Content Type in Storyblok       // By default will be contained by a folder called Category (change it in the Permalinks option in WP)       schema_mapping: {         "name": "name",         "slug": "slug",         "description": "content.description",         "parent": "content.parent",       }     },     // Add authors as categories.     {       name: 'posts', // Name of the post type in WP       new_content_type: 'post', // Name of the Content Type in Storyblok       folder: 'articles', // Name of the destination folder in Storyblok       schema_mapping: {         "date": "first_published_at",         "title": "name",         "slug": "slug",         "_links.wp:featuredmedia.0": "content.featured_image",         "excerpt": "content.excerpt",         "content": "content.content",       }     }     // More schemas...   ] })  wp2storyblok.migrate()

4. Create A Front-End Project

Now that the content is already stored in the Storyblok dashboard, it’s time to connect the Front-end project to Storyblok.

Whatever your framework or JS library, Storyblok provides the JavaScript client that will help you with the integration. In addition, in case you are using a specific framework, you will find other packages that will ease the way, like in Nuxt the storyblok-nuxt module.

This JavaScript API will also include a bridge between Storyblok and your Front-end application. The bridge is responsible for communicating via iframe with Storyblok to tell the editing interface which component to open when the user clicks on it.

Here is a list of tutorials you can find on Storyblok to connect your Front-end project.

Note: If you don’t find your technology among them, don’t worry there are many other tutorials on the Storyblok website, search for yours in the search engine, and if you don’t find one I encourage you to contact them, and you will help many more people!

5. Host Your Front-End Project And Automate Deploy

Once your project is ready to go into production, you choose a hosting provider and link your repository for easy deployment, then you ask yourself:

How do I redeploy my static site if I publish an entry on Storyblok?

The answer is very simple: by using the webhooks offered by Storyblok and the build hooks of your hosting.

To give you a real example, you can create build hooks URLs in Netlify within the deployment section; the URL created for Storyblok in the build hooks will go in the Settings → Webhooks → Story published & unpublished field in the Storyblok space.

Guides And Tools We Have Used During Migration

Let’s recap the links that have helped in the migration of the content and those that helped to understand the functioning of the REST API and the headless CMS to which you are migrating.

WP REST API Documentation Needed

REST API
Schemas

Migrating To Storyblok

General Info
Documentation
Global Components
SEO Related
Webhooks And Build Hooks
Scripts And Packages

Jamstack

Conclusion

After reading this article you will have what you need to understand why a headless setup will improve your project, how to migrate from your WordPress project to a headless CMS like Storyblok and how to keep improving and extending your project.

As you have seen, the possibilities of a headless setup are endless. After the migration, you will have enormous flexibility to scale your project, improve its performance and SEO, increase the productivity of the development team and stay on top of the latest trends.

Everyone is starting to migrate and there is more and more content and scripts that make it easier. What are you waiting for to migrate your WordPress?

Articles on Smashing Magazine — For Web Designers And Developers

07 Jul

How To Choose A Headless CMS

by TBSCategories: News

Web pages, such as the one you’re reading now, have text, images, videos and other assets to bring information to you. This data would be collated and authored in a Web Content Management System (WCMS) by a content editor. WCMSes have gone through an evolution moving from a Traditional CMS to a Decoupled CMS to a headless CMS.

Moving to a headless CMS is not an easy decision and the selection process should not be taken lightly. In this article, I will highlight a few core features that every headless CMS should provide. We will explore those features, the associated challenges and help you choose a headless CMS to satisfy your organization’s unique requirements.

As the Technical Director at Luminary, I have been helping our clients choose the best CMS, DXP (Digital Experience Platform) or headless CMS to suit their needs. With Luminary’s 21 years of experience in the digital space, my experience of 17 years in the CMS space as well as our focus on Headless since 2016, here are my two cents on what you should look out for.

Things To Consider When Choosing A Headless CMS

  • Concepts
  • For content authors
  • Authoring Roles
  • For developers
  • Other Factors

    • Monolithic vs Microservices

    We’ve explored the concepts behind headless CMSes in detail here on Smashing Magazine, but let’s do a quick recap. When it comes to a Traditional CMS, the CMS and the resulting front-end website are built on a monolithic architecture. The Traditional CMS tries and succeeds in many ways to serve the needs of the developer, content author, and marketer. For example, if the CMS is built on Microsoft’s .NET Framework, the front-end website would also be built on the same technology. All functionality and integrations would also have a tight dependency which in turn results in a large, cumbersome monolithic code base.

    Decoupled CMSes have removed this interdependence to a certain extent. This has been achieved by separating the front-end website from the CMS back-office and content repository.

    Monolithic architecture takes a back seat with headless CMSes. The CMS and every other integration is a microservice. The CMS itself is provided on a Software-as-a-Service (SaaS) model which I like to term Content-as-as-Service (CaaS). With this microservices architecture, everything you got from your Traditional CMS does not come out of the tin. You may have different services and vendors to provide you with the best of breed for each of your requirements.

    The move to a microservices mindset needs a bit of patience. We had marketers from a Traditional CMS background who resisted the idea of delving into multiple systems and services when using a headless CMS. We managed to take them along on the journey during selection and implementation of their headless CMS platform. Now, they are advocates for that headless CMS platform as it allows them to integrate new systems and services rather than being bound to one provided by a Traditional CMS.

    Look out for:

    • Reputed SaaS vendors
    • Integrating headless CMS as a microservice
    • Best of breed services

    Omnichannel At Its Core

    As much as a microservices mindset would help you when integrating a headless CMS, the true power of headless is realized in its omnichannel nature. An omnichannel experience revolves around your customer and creates a single customer experience across your brand by unifying sales and marketing. With a headless CMS, content is provided to different channels such as web, mobile, social, no-UI smart devices, IoT devices and even non-digital touchpoints such as a bricks-and-mortar shopfront.

    With a headless CMS, you need to define the schema for each content model from scratch. The process of defining this sound, logical taxonomy structure for the content items you create and publish is known as content modeling. If your first channel is going to be your website, make sure your content modeling takes omnichannel into account to alleviate any future pain. If you are only looking for a replacement CMS to just power your website, take another hard look at the Traditional or Decoupled CMS space to see if there’s something that would suit your requirements better.

    When modeling content schemas, think of the future. Working for a major airline not even a decade ago, I can remember trying to model content for mobile devices (yes! there was a separate subdomain for a mobile website). This was excruciatingly difficult since the content schemas were geared towards only a desktop website. But the story holds true even today that we need to be vigilant about content modeling.

    Look out for:

    • Channels you want to target
    • Good content modeling practices

    Creating Great Content

    Whether it is a traditional CMS or a headless CMS, the main requirement is managing content. Content authors should love working in the back-office. If you see authors turning to other authoring tools such as Google Docs for its commenting or suggestions capabilities, it may be a red flag as to what features you are missing.

    Microsoft word documents, spreadsheets, Google docs always rear their heads up when working with content authors. Rather than trying to banish them upfront, the easiest way to get content authors to work on the CMS is to give them the features they need and they will automatically phase those out. When we pushed Luminary’s own website live on a headless CMS, every team member (50 of them) was given enough access to add and edit their own profile for the website. It worked a treat without having 50 Google Docs flying all over the place.

    Editing Experience

    The decision to use a headless CMS may be an IT decision. But buy-in from the marketers and content authors within the organization is critical for its adoption and success. A headless CMS which allows content authors to enter content easily, find existing content and reuse content is something that should come out of the box.

    For ease of authoring content, having easy-to-use editors such as WYSIWYG editors, text editors, dropdowns and custom editors is a must. A clean and minimalist interface that allows a content author to focus on the task at hand will be appreciated. An editing interface that allows for concurrent editing, commenting, and creation of child content items in the same interface will increase the productivity of content authors.

    A word of caution when using WYSIWYG editors or heavy reliance on any editing interface which produces HTML. As a headless CMS is geared to cater to multiple channels, relying on WYSIWYG editors would take away the atomic nature of content which can be reused. Make sure that custom editors allow accessing data fields at a granular level. We have seen this hamper the reuse of content across different channels such as mobile and desktop for example.

    With a headless CMS, organizing content items in a tree structure is not the norm. But it is a bridge allowing content authors to transition easily from a Traditional CMS to a Headless one. If content items are not visualized in a tree structure, a strong search engine with facets and tagging capabilities is paramount for your content editors. This allows authors to find and reuse existing content easily.

    When reusing content, another aspect to consider is whether content items can be nested easily within other content items. This allows for maximum reuse of existing content. But beware of circular references to content which could cause headaches and performance issues. An example is a content item for a lawyer which is linked to a content item for an expertise. Then if the expertise content item is again linked to multiple Lawyer content items this could form a circular reference. Look for a headless CMS with smarts baked in to limit depth in the API and visualizations to show linked content items to avoid this pitfall.

    Look out for:

    • Authoring experience
    • Structure of content items
    • Ease of searching content
    • Overuse of WYSIWYG editors
    • Reusing content

    A Picture’s Worth: How To Handle Media

    A picture is worth a thousand words. But image assets are heavy to transport, difficult to organize, and hard to search. In a typical CMS, you will see duplicates and poorly named image assets over time. It is important that content editors are given tools to organize, categorize, tag, reuse and search for images within a headless CMS. For me, this means organizing assets in folders or containers. But it would be good to understand what your team requires in terms of managing static assets.

    The ability to upload a single image, set a focal point to it and then manipulate its dimensions and quality for different devices and screen sizes, brings massive time-savings to a content editor and even those designers/graphics artists who work behind the scenes. The delivery of static assets in formats such as WebP via a Content Delivery Network (CDN) is also crucial to serving your users a fast website.

    Most headless CMSes come with these features out of the box. If not, you need to decide which features you can live without. There’s a caveat to that rule. For extensive editing of the original images, you should stick to the best tools for the job such as Photoshop.

    Along with images, the next heaviest assets are videos. Once again, with the microservices mindset, streaming of videos should be left to service providers such as YouTube, Vimeo and other online streaming services. If your headless CMS can provide you with a nice editing interface to search or select a video from one of these providers, it’s a bonus.

    Look out for:

    • Organising images
    • Cropping and delivering images via a CDN
    • External best of breed video services

    Authoring Roles

    Who can enter content and who can approve or publish content to a live site and other granular permissions need to be managed via the headless CMS as well. A two-person team could survive without having distinct authoring roles, but as organizations and content teams grow, authoring roles are a must.

    I have worked with content teams of over 40 editors and this requirement needs to be carefully evaluated against the headless CMS you chose. If not, pandemonium will reign. With the team of 40 I worked with, we had copywriters, translators, QA personnel and legal approvers who had different permissions to access certain content, language variants, workflow approvals and publishing rights.

    The number of distinct roles and back-office users is usually how headless CMSes structure their pricing. When comparing price points between vendors think of current numbers and the future growth of your content team.

    Look out for:

    • Distinct roles
    • Number of back-office users

    Workflows

    Not every content item needs to be managed via a workflow. But when workflows, audit trails and approvals are necessary, the process needs to be managed within your headless CMS. Having a robust workflow built from the ground-up on your headless CMS gives you peace of mind and the opportunity to handle every content item according to your business process. The ability to integrate third-party systems via webhooks or APIs is a bonus you should watch out for.

    Look out for:

    • Robust workflows
    • Webhooks

    Content Previews

    The content editor has authored the content, added images and sent it via a workflow for approval. But where do they preview the content before it is made available to the general public? This is where preview APIs to retrieve unpublished content and the ability to set preview environments come into play.

    With a headless CMS, having moved away from a single channel mindset, your content editors should not expect to see full page previews within the CMS back-office. Each channel should have its own staging or preview environment to view yet-to-be-published draft content. This could be a staging site for your website or a locally installed version of your mobile app. A preview feature must be available in the pricing plan you have chosen for the headless CMS of your choice.

    Look out for:

    • Preview APIs from the vendor
    • Separate staging and production environments on your end

    Locales

    If your content needs to be served to different locales, that requirement needs to be identified early on in your project. Retrofitting is possible, but is not a fun activity. How you manage content and assets across cultures and languages should be thought out and documented. I would recommend creating a blueprint to identify which languages and assets inherit or default from another. Then make sure your choice of headless CMS supports that blueprint or explore avenues to achieve the same outcome differently.

    Look out for:

    • Internationalisation and Localisation support
    • Creating your own blueprint for handling locales

    Creating great content is always important. Thus, content authors should be given the best possible experience in their day-to-day activities to make your transition to headless CMS a success.

    Dev Time Is Precious

    With a headless CMS, developer involvement is a must. This could be a back-end developer or a front-end developer consuming the headless API to display content on the website. But once initial development is done, a content author should be able to work with minimal intervention. That’s the whole point of using a CMS. It stands true for headless CMSes too.

    As much as content authors are considered when comparing features, developer features should be explored as well. In this section, we will look at features that will save time for developers.

    APIs/GraphQL Support

    A mature API, that allows for selection, pagination and projection of content items, is critical for a developer to work with a headless CMS. Out-of-the-box GraphQL support is another defining factor as it will allow the developer to define the result they need at a very granular level. Comprehensive documentation and code samples are also a must.

    Make sure your developers are happy with the content retrieval APIs before committing to a headless CMS. Don’t forget preview APIs, secure APIs and the ease of using them via code. Do you want to automate content creation? Then content management APIs should be considered.

    Content Management APIs have been a blessing where we automated the import of over 2,000 blog posts from a WordPress site to a headless CMS. All the blog posts and related images were imported with minimal work for the content authors. Some headless CMSes offer Google Sheets Add-ons and other nifty tools to do this at a click of a button.

    With many headless CMSes offering free trials, it’s a good idea to take them on a test drive to see their suitability and conformance to your choice of content creation and retrieval.

    Look out for:

    • Mature REST APIs
    • GraphQL support
    • Preview and secure APIs
    • Content Management APIs for CRUD operations
    • Free trials to try it out

    Native SDKs

    Software Development Kits (SDKs) for various technologies, languages and platforms are available directly from the Headless vendor, an open-source initiative or a third-party. Make sure these SDKs support the technology, language and platform you will be building your website or consumer app on. As much as RESTful and GraphQL APIs allow you to query content, having a native SDK could reduce dev hours quite significantly.

    At Luminary, working with native SDKs for headless CMSes has allowed us to embrace the latest technologies such as Microsoft .NET Core and .NET 5. Also, building on an existing SDK has allowed us to follow the best practices recommended by the vendor while saving time.

    Look out for:

    • A supported SDK for your choice of technology, language, and platform.

    Environments

    A website or an app for a mom-and-pop shop might be able to curate and preview content with a single production environment. But as organizations, teams and features grow, multiple environments to curate and preview content become necessary. Not only does your headless CMS need to provide environments, but your consuming application should have environments set up as well. Methods to refresh content across environments need to be considered.

    Look out for:

    • Environments within your headless CMS
    • Ability to port content between environments

    Images, Files and CDNs

    We touched on managing images when talking about features for the content author. From a developer perspective, not only static assets need to be cached on a CDN. Many headless CMSes cache content retrieved via RESTful or GraphQL APIs. This speeds up the retrieval process and brings in performance improvements to your application.

    While CDN caching is super useful, there are times when cache corruption or older cached items could create issues. The ability to purge the CDN cache or the ability to pull in the latest content with specific HTTP headers should be a part of your headless CMS’ API functionality.

    The ability to use custom domains against a CDN to deliver your content or static assets might be a requirement you need to consider.

    Look out for:

    • Caching of images and content via CDN
    • Custom domain capabilities

    Usage Limits Across Plans

    Another factor to consider is the usage limits set for each plan you subscribe to on your choice of headless CMS. The number of content items, bandwidth consumption, the number of back-office users, the number of API calls, and rate limits need to be thought out. When planning for usage limits, consider current usage and future usage. Remember that many headless CMSes operate on a subscription basis and they do allow you to upgrade almost instantaneously to plans with higher limits.

    However, it’s worth being aware of how many users will be using the platform, and whether the solution would need to scale up massively. We witnessed a client get a very large bill as they unwittingly added a large number of users over their allocated quota. It’s a good idea for administrators to be aware of what their Headless plan offers and keep tabs on usage.

    Do consider keeping under usage limits on your current limits with client-side caching, static page generators and smart API or GraphQL calls to reduce your operating expenditure.

    Look out for:

    • Limits on certain features
    • Operating expense

    A developer’s time is expensive. Whereas a headless CMS is touted as a developer-friendly CMS, each vendor has different features they support natively. Understanding and comparing those against your developers’ needs is highly recommended.

    Other Factors

    There are a few other factors that may not impact the content author or the developer. This could range from marketing to finance to legal and regulatory requirements for your industry and your business.

    Data Centre Locations

    One question we often get asked is, where is the data stored? Yup, in the cloud. But which geographic data center is an important question due to the legal and regulatory requirements of certain businesses. A headless CMS which allows you to store data in the data center of your choice might be a critical factor in deciding which CMS you choose.

    Technical And Sales Support

    The ability to receive technical and sales support in your timezone is another deciding factor when choosing your headless CMS. Not having a local salesperson has tipped many projects in favor of those vendors who have people on the ground in the relevant region.

    We had a large NFP (Not for Profit) organization choose a headless CMS vendor due to the ability to store data in an Azure Data Centre within Australia. Having on-the-ground sales support and around-the-clock technical support clinched the sale for that headless CMS vendor.

    Look out for:

    • Legal and regulatory requirements of storing data
    • Local sales and technical support

    Enterprise Features To Consider

    Some large organizations might require a Single-sign-on (SSO) tied to the company’s authentication system or audit logs which can be easily queried. There might be integrations to existing systems and certain ISO certifications which need to be in place before a SaaS product is considered a right fit. Making a list of these enterprise features and others unique to your enterprise-level organization is a good starting point when choosing a headless CMS.

    The Community In Action

    Another usually overlooked area is the community around a given headless CMS. Are there people out there who are passionate about the product? I’m not talking about the vendor’s marketing peeps. Are there enough open-source resources shared by the people who are using the tool? This might not be a deciding factor but will help when you are in a tight spot during your implementation or support phase of a project.

    Infrastructure Integration

    With headless CMSes, you are not bound to technology, language or platform. The technology or platform on which the headless CMS is built does not influence the client application. You can use a technology of your choice from .NET to Node.js, your OS could be Windows, Linux or macOS, and your language could be anything from Python to C#.

    Similarly, when it comes to procuring infrastructure, you can choose to host your site on Netlify, Azure, GCP or AWS. The architecture of your website and its infrastructure decisions are now solely based on your requirements. There are also native first-class integrations with services like Gatsby Cloud which bring in more combos that make your life easier. For some, this could be a major decision and should be made by talking to some expert practitioners in the Headless space.

    Look out for:

    • Enterprise features you can’t live without
    • The community engagement with the vendor and the product
    • Support for your choice of Infrastructure

    Our Experience At Luminary

    At Luminary, we have been fortunate to partner with headless CMSes such as Acoustic, Contentful, Kentico Kontent, and Umbraco Heartcore. We have been working with some of these CMSes since the beta versions of their platforms. Public roadmaps, awesome technical support, and addressing our feature requests have been some of our highlights with these platforms.

    We’ve had experience with tackling SEO for Headless websites with front-end only implementations, caching large listing pages, dealing with large server-side caches, and integrating other microservices with headless CMSs. Each of these had its unique challenges which you should watch out for. Also, simple tasks on a Traditional CMS like form submissions and site search need to be well thought out along with more advanced features such as user authentication and authorization with third-party services.

    If you choose the correct headless CMS with the pointers above and with the correct implementation partner, you should end up with a headless CMS which makes happy marketers, happy content editors, and happy developers.

    Further Reading on SmashingMag:

Articles on Smashing Magazine — For Web Designers And Developers

07 Jul

How To Choose A Headless CMS

by TBSCategories: News

Web pages, such as the one you’re reading now, have text, images, videos and other assets to bring information to you. This data would be collated and authored in a Web Content Management System (WCMS) by a content editor. WCMSes have gone through an evolution moving from a Traditional CMS to a Decoupled CMS to a headless CMS.

Moving to a headless CMS is not an easy decision and the selection process should not be taken lightly. In this article, I will highlight a few core features that every headless CMS should provide. We will explore those features, the associated challenges and help you choose a headless CMS to satisfy your organization’s unique requirements.

As the Technical Director at Luminary, I have been helping our clients choose the best CMS, DXP (Digital Experience Platform) or headless CMS to suit their needs. With Luminary’s 21 years of experience in the digital space, my experience of 17 years in the CMS space as well as our focus on Headless since 2016, here are my two cents on what you should look out for.

Things To Consider When Choosing A Headless CMS

  • Concepts
  • For content authors
  • Authoring Roles
  • For developers
  • Other Factors

    • Monolithic vs Microservices

    We’ve explored the concepts behind headless CMSes in detail here on Smashing Magazine, but let’s do a quick recap. When it comes to a Traditional CMS, the CMS and the resulting front-end website are built on a monolithic architecture. The Traditional CMS tries and succeeds in many ways to serve the needs of the developer, content author, and marketer. For example, if the CMS is built on Microsoft’s .NET Framework, the front-end website would also be built on the same technology. All functionality and integrations would also have a tight dependency which in turn results in a large, cumbersome monolithic code base.

    Decoupled CMSes have removed this interdependence to a certain extent. This has been achieved by separating the front-end website from the CMS back-office and content repository.

    Monolithic architecture takes a back seat with headless CMSes. The CMS and every other integration is a microservice. The CMS itself is provided on a Software-as-a-Service (SaaS) model which I like to term Content-as-as-Service (CaaS). With this microservices architecture, everything you got from your Traditional CMS does not come out of the tin. You may have different services and vendors to provide you with the best of breed for each of your requirements.

    The move to a microservices mindset needs a bit of patience. We had marketers from a Traditional CMS background who resisted the idea of delving into multiple systems and services when using a headless CMS. We managed to take them along on the journey during selection and implementation of their headless CMS platform. Now, they are advocates for that headless CMS platform as it allows them to integrate new systems and services rather than being bound to one provided by a Traditional CMS.

    Look out for:

    • Reputed SaaS vendors
    • Integrating headless CMS as a microservice
    • Best of breed services

    Omnichannel At Its Core

    As much as a microservices mindset would help you when integrating a headless CMS, the true power of headless is realized in its omnichannel nature. An omnichannel experience revolves around your customer and creates a single customer experience across your brand by unifying sales and marketing. With a headless CMS, content is provided to different channels such as web, mobile, social, no-UI smart devices, IoT devices and even non-digital touchpoints such as a bricks-and-mortar shopfront.

    With a headless CMS, you need to define the schema for each content model from scratch. The process of defining this sound, logical taxonomy structure for the content items you create and publish is known as content modeling. If your first channel is going to be your website, make sure your content modeling takes omnichannel into account to alleviate any future pain. If you are only looking for a replacement CMS to just power your website, take another hard look at the Traditional or Decoupled CMS space to see if there’s something that would suit your requirements better.

    When modeling content schemas, think of the future. Working for a major airline not even a decade ago, I can remember trying to model content for mobile devices (yes! there was a separate subdomain for a mobile website). This was excruciatingly difficult since the content schemas were geared towards only a desktop website. But the story holds true even today that we need to be vigilant about content modeling.

    Look out for:

    • Channels you want to target
    • Good content modeling practices

    Creating Great Content

    Whether it is a traditional CMS or a headless CMS, the main requirement is managing content. Content authors should love working in the back-office. If you see authors turning to other authoring tools such as Google Docs for its commenting or suggestions capabilities, it may be a red flag as to what features you are missing.

    Microsoft word documents, spreadsheets, Google docs always rear their heads up when working with content authors. Rather than trying to banish them upfront, the easiest way to get content authors to work on the CMS is to give them the features they need and they will automatically phase those out. When we pushed Luminary’s own website live on a headless CMS, every team member (50 of them) was given enough access to add and edit their own profile for the website. It worked a treat without having 50 Google Docs flying all over the place.

    Editing Experience

    The decision to use a headless CMS may be an IT decision. But buy-in from the marketers and content authors within the organization is critical for its adoption and success. A headless CMS which allows content authors to enter content easily, find existing content and reuse content is something that should come out of the box.

    For ease of authoring content, having easy-to-use editors such as WYSIWYG editors, text editors, dropdowns and custom editors is a must. A clean and minimalist interface that allows a content author to focus on the task at hand will be appreciated. An editing interface that allows for concurrent editing, commenting, and creation of child content items in the same interface will increase the productivity of content authors.

    A word of caution when using WYSIWYG editors or heavy reliance on any editing interface which produces HTML. As a headless CMS is geared to cater to multiple channels, relying on WYSIWYG editors would take away the atomic nature of content which can be reused. Make sure that custom editors allow accessing data fields at a granular level. We have seen this hamper the reuse of content across different channels such as mobile and desktop for example.

    With a headless CMS, organizing content items in a tree structure is not the norm. But it is a bridge allowing content authors to transition easily from a Traditional CMS to a Headless one. If content items are not visualized in a tree structure, a strong search engine with facets and tagging capabilities is paramount for your content editors. This allows authors to find and reuse existing content easily.

    When reusing content, another aspect to consider is whether content items can be nested easily within other content items. This allows for maximum reuse of existing content. But beware of circular references to content which could cause headaches and performance issues. An example is a content item for a lawyer which is linked to a content item for an expertise. Then if the expertise content item is again linked to multiple Lawyer content items this could form a circular reference. Look for a headless CMS with smarts baked in to limit depth in the API and visualizations to show linked content items to avoid this pitfall.

    Look out for:

    • Authoring experience
    • Structure of content items
    • Ease of searching content
    • Overuse of WYSIWYG editors
    • Reusing content

    A Picture’s Worth: How To Handle Media

    A picture is worth a thousand words. But image assets are heavy to transport, difficult to organize, and hard to search. In a typical CMS, you will see duplicates and poorly named image assets over time. It is important that content editors are given tools to organize, categorize, tag, reuse and search for images within a headless CMS. For me, this means organizing assets in folders or containers. But it would be good to understand what your team requires in terms of managing static assets.

    The ability to upload a single image, set a focal point to it and then manipulate its dimensions and quality for different devices and screen sizes, brings massive time-savings to a content editor and even those designers/graphics artists who work behind the scenes. The delivery of static assets in formats such as WebP via a Content Delivery Network (CDN) is also crucial to serving your users a fast website.

    Most headless CMSes come with these features out of the box. If not, you need to decide which features you can live without. There’s a caveat to that rule. For extensive editing of the original images, you should stick to the best tools for the job such as Photoshop.

    Along with images, the next heaviest assets are videos. Once again, with the microservices mindset, streaming of videos should be left to service providers such as YouTube, Vimeo and other online streaming services. If your headless CMS can provide you with a nice editing interface to search or select a video from one of these providers, it’s a bonus.

    Look out for:

    • Organising images
    • Cropping and delivering images via a CDN
    • External best of breed video services

    Authoring Roles

    Who can enter content and who can approve or publish content to a live site and other granular permissions need to be managed via the headless CMS as well. A two-person team could survive without having distinct authoring roles, but as organizations and content teams grow, authoring roles are a must.

    I have worked with content teams of over 40 editors and this requirement needs to be carefully evaluated against the headless CMS you chose. If not, pandemonium will reign. With the team of 40 I worked with, we had copywriters, translators, QA personnel and legal approvers who had different permissions to access certain content, language variants, workflow approvals and publishing rights.

    The number of distinct roles and back-office users is usually how headless CMSes structure their pricing. When comparing price points between vendors think of current numbers and the future growth of your content team.

    Look out for:

    • Distinct roles
    • Number of back-office users

    Workflows

    Not every content item needs to be managed via a workflow. But when workflows, audit trails and approvals are necessary, the process needs to be managed within your headless CMS. Having a robust workflow built from the ground-up on your headless CMS gives you peace of mind and the opportunity to handle every content item according to your business process. The ability to integrate third-party systems via webhooks or APIs is a bonus you should watch out for.

    Look out for:

    • Robust workflows
    • Webhooks

    Content Previews

    The content editor has authored the content, added images and sent it via a workflow for approval. But where do they preview the content before it is made available to the general public? This is where preview APIs to retrieve unpublished content and the ability to set preview environments come into play.

    With a headless CMS, having moved away from a single channel mindset, your content editors should not expect to see full page previews within the CMS back-office. Each channel should have its own staging or preview environment to view yet-to-be-published draft content. This could be a staging site for your website or a locally installed version of your mobile app. A preview feature must be available in the pricing plan you have chosen for the headless CMS of your choice.

    Look out for:

    • Preview APIs from the vendor
    • Separate staging and production environments on your end

    Locales

    If your content needs to be served to different locales, that requirement needs to be identified early on in your project. Retrofitting is possible, but is not a fun activity. How you manage content and assets across cultures and languages should be thought out and documented. I would recommend creating a blueprint to identify which languages and assets inherit or default from another. Then make sure your choice of headless CMS supports that blueprint or explore avenues to achieve the same outcome differently.

    Look out for:

    • Internationalisation and Localisation support
    • Creating your own blueprint for handling locales

    Creating great content is always important. Thus, content authors should be given the best possible experience in their day-to-day activities to make your transition to headless CMS a success.

    Dev Time Is Precious

    With a headless CMS, developer involvement is a must. This could be a back-end developer or a front-end developer consuming the headless API to display content on the website. But once initial development is done, a content author should be able to work with minimal intervention. That’s the whole point of using a CMS. It stands true for headless CMSes too.

    As much as content authors are considered when comparing features, developer features should be explored as well. In this section, we will look at features that will save time for developers.

    APIs/GraphQL Support

    A mature API, that allows for selection, pagination and projection of content items, is critical for a developer to work with a headless CMS. Out-of-the-box GraphQL support is another defining factor as it will allow the developer to define the result they need at a very granular level. Comprehensive documentation and code samples are also a must.

    Make sure your developers are happy with the content retrieval APIs before committing to a headless CMS. Don’t forget preview APIs, secure APIs and the ease of using them via code. Do you want to automate content creation? Then content management APIs should be considered.

    Content Management APIs have been a blessing where we automated the import of over 2,000 blog posts from a WordPress site to a headless CMS. All the blog posts and related images were imported with minimal work for the content authors. Some headless CMSes offer Google Sheets Add-ons and other nifty tools to do this at a click of a button.

    With many headless CMSes offering free trials, it’s a good idea to take them on a test drive to see their suitability and conformance to your choice of content creation and retrieval.

    Look out for:

    • Mature REST APIs
    • GraphQL support
    • Preview and secure APIs
    • Content Management APIs for CRUD operations
    • Free trials to try it out

    Native SDKs

    Software Development Kits (SDKs) for various technologies, languages and platforms are available directly from the Headless vendor, an open-source initiative or a third-party. Make sure these SDKs support the technology, language and platform you will be building your website or consumer app on. As much as RESTful and GraphQL APIs allow you to query content, having a native SDK could reduce dev hours quite significantly.

    At Luminary, working with native SDKs for headless CMSes has allowed us to embrace the latest technologies such as Microsoft .NET Core and .NET 5. Also, building on an existing SDK has allowed us to follow the best practices recommended by the vendor while saving time.

    Look out for:

    • A supported SDK for your choice of technology, language, and platform.

    Environments

    A website or an app for a mom-and-pop shop might be able to curate and preview content with a single production environment. But as organizations, teams and features grow, multiple environments to curate and preview content become necessary. Not only does your headless CMS need to provide environments, but your consuming application should have environments set up as well. Methods to refresh content across environments need to be considered.

    Look out for:

    • Environments within your headless CMS
    • Ability to port content between environments

    Images, Files and CDNs

    We touched on managing images when talking about features for the content author. From a developer perspective, not only static assets need to be cached on a CDN. Many headless CMSes cache content retrieved via RESTful or GraphQL APIs. This speeds up the retrieval process and brings in performance improvements to your application.

    While CDN caching is super useful, there are times when cache corruption or older cached items could create issues. The ability to purge the CDN cache or the ability to pull in the latest content with specific HTTP headers should be a part of your headless CMS’ API functionality.

    The ability to use custom domains against a CDN to deliver your content or static assets might be a requirement you need to consider.

    Look out for:

    • Caching of images and content via CDN
    • Custom domain capabilities

    Usage Limits Across Plans

    Another factor to consider is the usage limits set for each plan you subscribe to on your choice of headless CMS. The number of content items, bandwidth consumption, the number of back-office users, the number of API calls, and rate limits need to be thought out. When planning for usage limits, consider current usage and future usage. Remember that many headless CMSes operate on a subscription basis and they do allow you to upgrade almost instantaneously to plans with higher limits.

    However, it’s worth being aware of how many users will be using the platform, and whether the solution would need to scale up massively. We witnessed a client get a very large bill as they unwittingly added a large number of users over their allocated quota. It’s a good idea for administrators to be aware of what their Headless plan offers and keep tabs on usage.

    Do consider keeping under usage limits on your current limits with client-side caching, static page generators and smart API or GraphQL calls to reduce your operating expenditure.

    Look out for:

    • Limits on certain features
    • Operating expense

    A developer’s time is expensive. Whereas a headless CMS is touted as a developer-friendly CMS, each vendor has different features they support natively. Understanding and comparing those against your developers’ needs is highly recommended.

    Other Factors

    There are a few other factors that may not impact the content author or the developer. This could range from marketing to finance to legal and regulatory requirements for your industry and your business.

    Data Centre Locations

    One question we often get asked is, where is the data stored? Yup, in the cloud. But which geographic data center is an important question due to the legal and regulatory requirements of certain businesses. A headless CMS which allows you to store data in the data center of your choice might be a critical factor in deciding which CMS you choose.

    Technical And Sales Support

    The ability to receive technical and sales support in your timezone is another deciding factor when choosing your headless CMS. Not having a local salesperson has tipped many projects in favor of those vendors who have people on the ground in the relevant region.

    We had a large NFP (Not for Profit) organization choose a headless CMS vendor due to the ability to store data in an Azure Data Centre within Australia. Having on-the-ground sales support and around-the-clock technical support clinched the sale for that headless CMS vendor.

    Look out for:

    • Legal and regulatory requirements of storing data
    • Local sales and technical support

    Enterprise Features To Consider

    Some large organizations might require a Single-sign-on (SSO) tied to the company’s authentication system or audit logs which can be easily queried. There might be integrations to existing systems and certain ISO certifications which need to be in place before a SaaS product is considered a right fit. Making a list of these enterprise features and others unique to your enterprise-level organization is a good starting point when choosing a headless CMS.

    The Community In Action

    Another usually overlooked area is the community around a given headless CMS. Are there people out there who are passionate about the product? I’m not talking about the vendor’s marketing peeps. Are there enough open-source resources shared by the people who are using the tool? This might not be a deciding factor but will help when you are in a tight spot during your implementation or support phase of a project.

    Infrastructure Integration

    With headless CMSes, you are not bound to technology, language or platform. The technology or platform on which the headless CMS is built does not influence the client application. You can use a technology of your choice from .NET to Node.js, your OS could be Windows, Linux or macOS, and your language could be anything from Python to C#.

    Similarly, when it comes to procuring infrastructure, you can choose to host your site on Netlify, Azure, GCP or AWS. The architecture of your website and its infrastructure decisions are now solely based on your requirements. There are also native first-class integrations with services like Gatsby Cloud which bring in more combos that make your life easier. For some, this could be a major decision and should be made by talking to some expert practitioners in the Headless space.

    Look out for:

    • Enterprise features you can’t live without
    • The community engagement with the vendor and the product
    • Support for your choice of Infrastructure

    Our Experience At Luminary

    At Luminary, we have been fortunate to partner with headless CMSes such as Acoustic, Contentful, Kentico Kontent, and Umbraco Heartcore. We have been working with some of these CMSes since the beta versions of their platforms. Public roadmaps, awesome technical support, and addressing our feature requests have been some of our highlights with these platforms.

    We’ve had experience with tackling SEO for Headless websites with front-end only implementations, caching large listing pages, dealing with large server-side caches, and integrating other microservices with headless CMSs. Each of these had its unique challenges which you should watch out for. Also, simple tasks on a Traditional CMS like form submissions and site search need to be well thought out along with more advanced features such as user authentication and authorization with third-party services.

    If you choose the correct headless CMS with the pointers above and with the correct implementation partner, you should end up with a headless CMS which makes happy marketers, happy content editors, and happy developers.

    Further Reading on SmashingMag:

Articles on Smashing Magazine — For Web Designers And Developers

06 Jul

How To Choose A Headless CMS

by TBSCategories: News

Web pages, such as the one you’re reading now, have text, images, videos and other assets to bring information to you. This data would be collated and authored in a Web Content Management System (WCMS) by a content editor. WCMSes have gone through an evolution moving from a Traditional CMS to a Decoupled CMS to a headless CMS.

Moving to a headless CMS is not an easy decision and the selection process should not be taken lightly. In this article, I will highlight a few core features that every headless CMS should provide. We will explore those features, the associated challenges and help you choose a headless CMS to satisfy your organization’s unique requirements.

As the Technical Director at Luminary, I have been helping our clients choose the best CMS, DXP (Digital Experience Platform) or headless CMS to suit their needs. With Luminary’s 21 years of experience in the digital space, my experience of 17 years in the CMS space as well as our focus on Headless since 2016, here are my two cents on what you should look out for.

Things To Consider When Choosing A Headless CMS

  • Concepts
  • For content authors
  • Authoring Roles
  • For developers
  • Other Factors

    • Monolithic vs Microservices

    We’ve explored the concepts behind headless CMSes in detail here on Smashing Magazine, but let’s do a quick recap. When it comes to a Traditional CMS, the CMS and the resulting front-end website are built on a monolithic architecture. The Traditional CMS tries and succeeds in many ways to serve the needs of the developer, content author, and marketer. For example, if the CMS is built on Microsoft’s .NET Framework, the front-end website would also be built on the same technology. All functionality and integrations would also have a tight dependency which in turn results in a large, cumbersome monolithic code base.

    Decoupled CMSes have removed this interdependence to a certain extent. This has been achieved by separating the front-end website from the CMS back-office and content repository.

    Monolithic architecture takes a back seat with headless CMSes. The CMS and every other integration is a microservice. The CMS itself is provided on a Software-as-a-Service (SaaS) model which I like to term Content-as-as-Service (CaaS). With this microservices architecture, everything you got from your Traditional CMS does not come out of the tin. You may have different services and vendors to provide you with the best of breed for each of your requirements.

    The move to a microservices mindset needs a bit of patience. We had marketers from a Traditional CMS background who resisted the idea of delving into multiple systems and services when using a headless CMS. We managed to take them along on the journey during selection and implementation of their headless CMS platform. Now, they are advocates for that headless CMS platform as it allows them to integrate new systems and services rather than being bound to one provided by a Traditional CMS.

    Look out for:

    • Reputed SaaS vendors
    • Integrating headless CMS as a microservice
    • Best of breed services

    Omnichannel At Its Core

    As much as a microservices mindset would help you when integrating a headless CMS, the true power of headless is realized in its omnichannel nature. An omnichannel experience revolves around your customer and creates a single customer experience across your brand by unifying sales and marketing. With a headless CMS, content is provided to different channels such as web, mobile, social, no-UI smart devices, IoT devices and even non-digital touchpoints such as a bricks-and-mortar shopfront.

    With a headless CMS, you need to define the schema for each content model from scratch. The process of defining this sound, logical taxonomy structure for the content items you create and publish is known as content modeling. If your first channel is going to be your website, make sure your content modeling takes omnichannel into account to alleviate any future pain. If you are only looking for a replacement CMS to just power your website, take another hard look at the Traditional or Decoupled CMS space to see if there’s something that would suit your requirements better.

    When modeling content schemas, think of the future. Working for a major airline not even a decade ago, I can remember trying to model content for mobile devices (yes! there was a separate subdomain for a mobile website). This was excruciatingly difficult since the content schemas were geared towards only a desktop website. But the story holds true even today that we need to be vigilant about content modeling.

    Look out for:

    • Channels you want to target
    • Good content modeling practices

    Creating Great Content

    Whether it is a traditional CMS or a headless CMS, the main requirement is managing content. Content authors should love working in the back-office. If you see authors turning to other authoring tools such as Google Docs for its commenting or suggestions capabilities, it may be a red flag as to what features you are missing.

    Microsoft word documents, spreadsheets, Google docs always rear their heads up when working with content authors. Rather than trying to banish them upfront, the easiest way to get content authors to work on the CMS is to give them the features they need and they will automatically phase those out. When we pushed Luminary’s own website live on a headless CMS, every team member (50 of them) was given enough access to add and edit their own profile for the website. It worked a treat without having 50 Google Docs flying all over the place.

    Editing Experience

    The decision to use a headless CMS may be an IT decision. But buy-in from the marketers and content authors within the organization is critical for its adoption and success. A headless CMS which allows content authors to enter content easily, find existing content and reuse content is something that should come out of the box.

    For ease of authoring content, having easy-to-use editors such as WYSIWYG editors, text editors, dropdowns and custom editors is a must. A clean and minimalist interface that allows a content author to focus on the task at hand will be appreciated. An editing interface that allows for concurrent editing, commenting, and creation of child content items in the same interface will increase the productivity of content authors.

    A word of caution when using WYSIWYG editors or heavy reliance on any editing interface which produces HTML. As a headless CMS is geared to cater to multiple channels, relying on WYSIWYG editors would take away the atomic nature of content which can be reused. Make sure that custom editors allow accessing data fields at a granular level. We have seen this hamper the reuse of content across different channels such as mobile and desktop for example.

    With a headless CMS, organizing content items in a tree structure is not the norm. But it is a bridge allowing content authors to transition easily from a Traditional CMS to a Headless one. If content items are not visualized in a tree structure, a strong search engine with facets and tagging capabilities is paramount for your content editors. This allows authors to find and reuse existing content easily.

    When reusing content, another aspect to consider is whether content items can be nested easily within other content items. This allows for maximum reuse of existing content. But beware of circular references to content which could cause headaches and performance issues. An example is a content item for a lawyer which is linked to a content item for an expertise. Then if the expertise content item is again linked to multiple Lawyer content items this could form a circular reference. Look for a headless CMS with smarts baked in to limit depth in the API and visualizations to show linked content items to avoid this pitfall.

    Look out for:

    • Authoring experience
    • Structure of content items
    • Ease of searching content
    • Overuse of WYSIWYG editors
    • Reusing content

    A Picture’s Worth: How To Handle Media

    A picture is worth a thousand words. But image assets are heavy to transport, difficult to organize, and hard to search. In a typical CMS, you will see duplicates and poorly named image assets over time. It is important that content editors are given tools to organize, categorize, tag, reuse and search for images within a headless CMS. For me, this means organizing assets in folders or containers. But it would be good to understand what your team requires in terms of managing static assets.

    The ability to upload a single image, set a focal point to it and then manipulate its dimensions and quality for different devices and screen sizes, brings massive time-savings to a content editor and even those designers/graphics artists who work behind the scenes. The delivery of static assets in formats such as WebP via a Content Delivery Network (CDN) is also crucial to serving your users a fast website.

    Most headless CMSes come with these features out of the box. If not, you need to decide which features you can live without. There’s a caveat to that rule. For extensive editing of the original images, you should stick to the best tools for the job such as Photoshop.

    Along with images, the next heaviest assets are videos. Once again, with the microservices mindset, streaming of videos should be left to service providers such as YouTube, Vimeo and other online streaming services. If your headless CMS can provide you with a nice editing interface to search or select a video from one of these providers, it’s a bonus.

    Look out for:

    • Organising images
    • Cropping and delivering images via a CDN
    • External best of breed video services

    Authoring Roles

    Who can enter content and who can approve or publish content to a live site and other granular permissions need to be managed via the headless CMS as well. A two-person team could survive without having distinct authoring roles, but as organizations and content teams grow, authoring roles are a must.

    I have worked with content teams of over 40 editors and this requirement needs to be carefully evaluated against the headless CMS you chose. If not, pandemonium will reign. With the team of 40 I worked with, we had copywriters, translators, QA personnel and legal approvers who had different permissions to access certain content, language variants, workflow approvals and publishing rights.

    The number of distinct roles and back-office users is usually how headless CMSes structure their pricing. When comparing price points between vendors think of current numbers and the future growth of your content team.

    Look out for:

    • Distinct roles
    • Number of back-office users

    Workflows

    Not every content item needs to be managed via a workflow. But when workflows, audit trails and approvals are necessary, the process needs to be managed within your headless CMS. Having a robust workflow built from the ground-up on your headless CMS gives you peace of mind and the opportunity to handle every content item according to your business process. The ability to integrate third-party systems via webhooks or APIs is a bonus you should watch out for.

    Look out for:

    • Robust workflows
    • Webhooks

    Content Previews

    The content editor has authored the content, added images and sent it via a workflow for approval. But where do they preview the content before it is made available to the general public? This is where preview APIs to retrieve unpublished content and the ability to set preview environments come into play.

    With a headless CMS, having moved away from a single channel mindset, your content editors should not expect to see full page previews within the CMS back-office. Each channel should have its own staging or preview environment to view yet-to-be-published draft content. This could be a staging site for your website or a locally installed version of your mobile app. A preview feature must be available in the pricing plan you have chosen for the headless CMS of your choice.

    Look out for:

    • Preview APIs from the vendor
    • Separate staging and production environments on your end

    Locales

    If your content needs to be served to different locales, that requirement needs to be identified early on in your project. Retrofitting is possible, but is not a fun activity. How you manage content and assets across cultures and languages should be thought out and documented. I would recommend creating a blueprint to identify which languages and assets inherit or default from another. Then make sure your choice of headless CMS supports that blueprint or explore avenues to achieve the same outcome differently.

    Look out for:

    • Internationalisation and Localisation support
    • Creating your own blueprint for handling locales

    Creating great content is always important. Thus, content authors should be given the best possible experience in their day-to-day activities to make your transition to headless CMS a success.

    Dev Time Is Precious

    With a headless CMS, developer involvement is a must. This could be a back-end developer or a front-end developer consuming the headless API to display content on the website. But once initial development is done, a content author should be able to work with minimal intervention. That’s the whole point of using a CMS. It stands true for headless CMSes too.

    As much as content authors are considered when comparing features, developer features should be explored as well. In this section, we will look at features that will save time for developers.

    APIs/GraphQL Support

    A mature API, that allows for selection, pagination and projection of content items, is critical for a developer to work with a headless CMS. Out-of-the-box GraphQL support is another defining factor as it will allow the developer to define the result they need at a very granular level. Comprehensive documentation and code samples are also a must.

    Make sure your developers are happy with the content retrieval APIs before committing to a headless CMS. Don’t forget preview APIs, secure APIs and the ease of using them via code. Do you want to automate content creation? Then content management APIs should be considered.

    Content Management APIs have been a blessing where we automated the import of over 2,000 blog posts from a WordPress site to a headless CMS. All the blog posts and related images were imported with minimal work for the content authors. Some headless CMSes offer Google Sheets Add-ons and other nifty tools to do this at a click of a button.

    With many headless CMSes offering free trials, it’s a good idea to take them on a test drive to see their suitability and conformance to your choice of content creation and retrieval.

    Look out for:

    • Mature REST APIs
    • GraphQL support
    • Preview and secure APIs
    • Content Management APIs for CRUD operations
    • Free trials to try it out

    Native SDKs

    Software Development Kits (SDKs) for various technologies, languages and platforms are available directly from the Headless vendor, an open-source initiative or a third-party. Make sure these SDKs support the technology, language and platform you will be building your website or consumer app on. As much as RESTful and GraphQL APIs allow you to query content, having a native SDK could reduce dev hours quite significantly.

    At Luminary, working with native SDKs for headless CMSes has allowed us to embrace the latest technologies such as Microsoft .NET Core and .NET 5. Also, building on an existing SDK has allowed us to follow the best practices recommended by the vendor while saving time.

    Look out for:

    • A supported SDK for your choice of technology, language, and platform.

    Environments

    A website or an app for a mom-and-pop shop might be able to curate and preview content with a single production environment. But as organizations, teams and features grow, multiple environments to curate and preview content become necessary. Not only does your headless CMS need to provide environments, but your consuming application should have environments set up as well. Methods to refresh content across environments need to be considered.

    Look out for:

    • Environments within your headless CMS
    • Ability to port content between environments

    Images, Files and CDNs

    We touched on managing images when talking about features for the content author. From a developer perspective, not only static assets need to be cached on a CDN. Many headless CMSes cache content retrieved via RESTful or GraphQL APIs. This speeds up the retrieval process and brings in performance improvements to your application.

    While CDN caching is super useful, there are times when cache corruption or older cached items could create issues. The ability to purge the CDN cache or the ability to pull in the latest content with specific HTTP headers should be a part of your headless CMS’ API functionality.

    The ability to use custom domains against a CDN to deliver your content or static assets might be a requirement you need to consider.

    Look out for:

    • Caching of images and content via CDN
    • Custom domain capabilities

    Usage Limits Across Plans

    Another factor to consider is the usage limits set for each plan you subscribe to on your choice of headless CMS. The number of content items, bandwidth consumption, the number of back-office users, the number of API calls, and rate limits need to be thought out. When planning for usage limits, consider current usage and future usage. Remember that many headless CMSes operate on a subscription basis and they do allow you to upgrade almost instantaneously to plans with higher limits.

    However, it’s worth being aware of how many users will be using the platform, and whether the solution would need to scale up massively. We witnessed a client get a very large bill as they unwittingly added a large number of users over their allocated quota. It’s a good idea for administrators to be aware of what their Headless plan offers and keep tabs on usage.

    Do consider keeping under usage limits on your current limits with client-side caching, static page generators and smart API or GraphQL calls to reduce your operating expenditure.

    Look out for:

    • Limits on certain features
    • Operating expense

    A developer’s time is expensive. Whereas a headless CMS is touted as a developer-friendly CMS, each vendor has different features they support natively. Understanding and comparing those against your developers’ needs is highly recommended.

    Other Factors

    There are a few other factors that may not impact the content author or the developer. This could range from marketing to finance to legal and regulatory requirements for your industry and your business.

    Data Centre Locations

    One question we often get asked is, where is the data stored? Yup, in the cloud. But which geographic data center is an important question due to the legal and regulatory requirements of certain businesses. A headless CMS which allows you to store data in the data center of your choice might be a critical factor in deciding which CMS you choose.

    Technical And Sales Support

    The ability to receive technical and sales support in your timezone is another deciding factor when choosing your headless CMS. Not having a local salesperson has tipped many projects in favor of those vendors who have people on the ground in the relevant region.

    We had a large NFP (Not for Profit) organization choose a headless CMS vendor due to the ability to store data in an Azure Data Centre within Australia. Having on-the-ground sales support and around-the-clock technical support clinched the sale for that headless CMS vendor.

    Look out for:

    • Legal and regulatory requirements of storing data
    • Local sales and technical support

    Enterprise Features To Consider

    Some large organizations might require a Single-sign-on (SSO) tied to the company’s authentication system or audit logs which can be easily queried. There might be integrations to existing systems and certain ISO certifications which need to be in place before a SaaS product is considered a right fit. Making a list of these enterprise features and others unique to your enterprise-level organization is a good starting point when choosing a headless CMS.

    The Community In Action

    Another usually overlooked area is the community around a given headless CMS. Are there people out there who are passionate about the product? I’m not talking about the vendor’s marketing peeps. Are there enough open-source resources shared by the people who are using the tool? This might not be a deciding factor but will help when you are in a tight spot during your implementation or support phase of a project.

    Infrastructure Integration

    With headless CMSes, you are not bound to technology, language or platform. The technology or platform on which the headless CMS is built does not influence the client application. You can use a technology of your choice from .NET to Node.js, your OS could be Windows, Linux or macOS, and your language could be anything from Python to C#.

    Similarly, when it comes to procuring infrastructure, you can choose to host your site on Netlify, Azure, GCP or AWS. The architecture of your website and its infrastructure decisions are now solely based on your requirements. There are also native first-class integrations with services like Gatsby Cloud which bring in more combos that make your life easier. For some, this could be a major decision and should be made by talking to some expert practitioners in the Headless space.

    Look out for:

    • Enterprise features you can’t live without
    • The community engagement with the vendor and the product
    • Support for your choice of Infrastructure

    Our Experience At Luminary

    At Luminary, we have been fortunate to partner with headless CMSes such as Acoustic, Contentful, Kentico Kontent, and Umbraco Heartcore. We have been working with some of these CMSes since the beta versions of their platforms. Public roadmaps, awesome technical support, and addressing our feature requests have been some of our highlights with these platforms.

    We’ve had experience with tackling SEO for Headless websites with front-end only implementations, caching large listing pages, dealing with large server-side caches, and integrating other microservices with headless CMSs. Each of these had its unique challenges which you should watch out for. Also, simple tasks on a Traditional CMS like form submissions and site search need to be well thought out along with more advanced features such as user authentication and authorization with third-party services.

    If you choose the correct headless CMS with the pointers above and with the correct implementation partner, you should end up with a headless CMS which makes happy marketers, happy content editors, and happy developers.

    Further Reading on SmashingMag:

Articles on Smashing Magazine — For Web Designers And Developers

Newer postsOlder posts
×

Powered by WhatsApp Chat

WhatsApp Chat is free, download and try it now here!

× Chat with Us