Migrating WordPress articles to Storyblok

In this tutorial, you'll learn how to migrate WordPress articles to Storyblok using the Storyblok WordPress Importer.

Why migrate to Storyblok?

While WordPress is open-source and widely used, it is a monolithic CMS that can become limiting as your business scales. Features like content planning, workflows, and omnichannel support are either unavailable or difficult to implement.

Storyblok, on the other hand, is a modular, headless CMS. Its powerful APIs give developers the freedom to use any tech stack, and its visual editor provides an enhanced editorial experience. With Storyblok, you can scale seamlessly without worrying about hosting, security, or infrastructure limitations.

Understanding the Storyblok WordPress Importer

The Storyblok WordPress Importer, created by Storyblok, simplifies the migration process. The script allows you to map WordPress API fields to Storyblok fields. For example:

        
      {
  name: "posts",
  new_content_type: "post",
  folder: "articles",
  schema_mapping: {
    title: "name",
    slug: "slug",
    content: "content.content",
    "_links.wp:featuredmedia.0": "content.featured_image"
  }
}
    

Refer to the WordPress API documentation to understand the available fields.

Preparing for migration

1. Create a Storyblok Account: Sign up here.
2. Set Up a Storyblok Space: Learn how to create a space and design content schemas in the Getting Started Guide.
3. Generate a Personal Access Token: Follow this guide to obtain your token.

Designing the content schema

Before migrating, we need to replicate the WordPress schema in Storyblok. If you're not familiar with Storyblok schema design, you can start here.

Once you're comfortable with it, let's create the following content schemas in Storyblok:

• Category (Content Type Block):
  • description (Text)
• Author (Content Type Block):
  • bio (Text)
• Post (Content Type Block):
  • featured_image (Asset)
  • excerpt (Richtext)
  • content (Richtext)
  • categories (Multi-option References)
  • author (Single-option Reference)

Configure relationships so that articles can reference authors and categories.

Mapping WordPress content to Storyblok

1. Clone the Storyblok WordPress Importer repository.
2. Create a new file, migrate.js, and add the following code:

   migrate.js Copy to clipboard

           
         import { Wp2Storyblok } from './index.js';
   
   const wp2storyblok = new Wp2Storyblok(
     'http://wordpress-storyblok.local/wp-json',
     {
       token: 'YOUR_MAPI_ACCESS_TOKEN',
       space_id: YOUR_SPACE_ID,
       content_types: [
         {
           name: 'categories',
           new_content_type: 'category',
           schema_mapping: {
             name: 'name',
             slug: 'slug',
             description: 'content.description',
           },
         },
         {
           name: 'users',
           new_content_type: 'author',
           schema_mapping: {
             name: 'name',
             slug: 'slug',
             description: 'content.bio',
           },
         },
         {
           name: 'posts',
           new_content_type: 'post',
           folder: 'post',
           taxonomies: [
             {
               name: 'categories',
               field: 'categories',
               type: 'relationship',
             },
             {
               name: 'users',
               field: 'author',
               type: 'relationship',
             },
           ],
           schema_mapping: {
             date: 'first_published_at',
             title: 'name',
             slug: 'slug',
             '_links.wp:featuredmedia.0': 'content.featured_image',
             excerpt: 'content.excerpt',
             content: 'content.content',
             categories: 'content.categories',
             author: 'content.author',
           },
         },
       ],
     }
   );
   
   wp2storyblok.migrate();
       

   In the code above, we are mapping all WordPress API properties to the corresponding fields we modeled in Storyblok. For example, in the WordPress API response, there is a field _links.wp:featuredmedia.0, which has been mapped to featured_image in Storyblok. We follow the same pattern for all other fields as well.You can also refer to the Storyblok MAPI docs if you want to dive deeper.
3. Run the script using:

   Copy to clipboard

           
         node migrate.js
       

4. Verify the migrated content in your Storyblok space.

Best practices

• Take the opportunity to optimize your schema. Storyblok's dynamic API allows you to fetch only the required data, making it efficient.
• Name your fields meaningfully to reflect their purpose clearly.
• Consider what you actually need to migrate—for example, just news articles. This is a common scenario and allows you to design a more suitable content model for other sections of the site separately.

Next steps

Explore how to use Storyblok with modern frameworks like Astro, Next.js, or Remix to build your frontend. Check out the following resources:

• Getting Started with Astro
• Getting Started with Next.js
• Getting Started with Remix