Migrating from Magento to Storyblok: A Practical Technical Example

Migrating from Magento to Storyblok is a common modernization path for organizations that want to decouple content from commerce while improving performance, flexibility, and editorial experience.

Magento is a powerful commerce platform, but its CMS capabilities are often tightly coupled to page templates and frontend rendering logic. Storyblok, by contrast, enables structured content and component-based editing, making it easier to reuse content across multiple channels.

This article walks through a practical example of migrating marketing content from Magento into Storyblok using a scripted approach.

Migration Scenario

In this example:

• Source platform: Magento CMS pages
• Target platform: Storyblok
• Content types: marketing pages, landing pages, promotional content
• Migration method: scripted ETL pipeline
• Output: structured Storyblok components

Example Magento page:

• title
• url key
• content (HTML)
• meta description
• meta title
• media references

Typical Magento content is stored as HTML inside a single field, often mixing structure and presentation.

Target Component Model in Storyblok

Instead of storing entire pages as HTML blobs, Storyblok encourages structured components.

Example component structure:

Page

• Hero component
• Rich text component
• Image component
• CTA component
• SEO metadata fields

Example Storyblok schema:

Page component fields:

• title (text)
• slug (text)
• body (blocks)
• seo (nested component)

SEO component:

• metaTitle
• metaDescription
• ogImage

Step 1: Extract Content from Magento

Magento content can be extracted using:

• Magento REST API
• direct database query
• export tools
• integration middleware

Example REST request:

GET /rest/V1/cmsPage/search

Example extracted JSON:

{
  "id": 12,
  "title": "Investment Solutions",
  "identifier": "investment-solutions",
  "content": "<h2>Investment solutions</h2><p>We provide...</p>",
  "meta_title": "Investment Solutions",
  "meta_description": "Learn about investment strategies"
}

Extraction scripts should:

• preserve identifiers
• capture SEO metadata
• identify media references
• capture internal links

Step 2: Convert HTML into Structured Components

Magento stores most content as HTML.

Storyblok rich text fields use a structured JSON format.

Example transformation:

Input HTML:

<h2>Investment solutions</h2>
<p>We provide tailored strategies.</p>

Converted rich text JSON:

{
  "type": "doc",
  "content": [
    {
      "type": "heading",
      "attrs": { "level": 2 },
      "content": [
        {
          "type": "text",
          "text": "Investment solutions"
        }
      ]
    },
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "text": "We provide tailored strategies."
        }
      ]
    }
  ]
}

HTML parsing libraries commonly used:

• cheerio (Node.js)
• html agility pack (.NET)
• jsdom
• parse5

Transformation tasks typically include:

• mapping headings to structured nodes
• converting links to Storyblok link format
• removing inline styling
• normalizing whitespace
• splitting content into logical components

Step 3: Map Magento Fields to Storyblok Schema

Example transformation mapping:

Magento field	Storyblok field
title	title
identifier	slug
content	rich_text blok
meta_title	seo.metaTitle
meta_description	seo.metaDescription

Example transformed payload:

{
  "name": "Investment Solutions",
  "slug": "investment-solutions",
  "content": {
    "component": "page",
    "body": [
      {
        "component": "rich_text",
        "text": { ... }
      }
    ],
    "seo": {
      "component": "seo",
      "metaTitle": "Investment Solutions",
      "metaDescription": "Learn about investment strategies"
    }
  }
}

Step 4: Upload Content Using Storyblok Management API

Example Node.js import script:

import StoryblokClient from "storyblok-js-client"

const client = new StoryblokClient({
  oauthToken: process.env.STORYBLOK_TOKEN
})

async function createStory(payload) {
  return client.post("spaces/123456/stories", {
    story: payload
  })
}

Batch import example:

for (const page of pages) {
  const transformed = transform(page)

  await createStory(transformed)
}

Recommended best practices:

• log imported IDs
• support re-runs safely
• skip unchanged content
• track migration status

Step 5: Migrate Images and Media

Magento content often references media paths:

/media/catalog/product/banner.jpg

Migration workflow:

1. download media file
2. upload to Storyblok asset service
3. replace URLs in rich text JSON

Example upload request:

POST https://api.storyblok.com/v2/spaces/:space_id/assets

Typical automation steps:

• detect duplicate assets
• preserve alt text metadata
• optimize image sizes
• update structured references

Media migration often surfaces hidden inconsistencies in legacy content.

Step 6: Handle Internal Links

Magento internal links often use relative paths:

/investment-solutions

Storyblok links may use:

• UUID references
• slug references
• full URLs

Migration scripts typically:

• build slug lookup dictionaries
• convert internal links to structured link objects
• validate link targets exist

Example link structure:

{
  "linktype": "story",
  "cached_url": "investment-solutions"
}

Step 7: Validate Migrated Content

Validation checks:

• missing components
• broken internal links
• duplicate slugs
• empty rich text nodes
• missing SEO metadata

Automated QA scripts can compare:

• page counts
• slug lists
• metadata completeness
• content length

Preview environments allow editors to review migrated content visually.

Example End-to-End Migration Flow

Pipeline overview:

Extract Magento pages → transform HTML → upload assets → map fields → import stories → validate structure → publish

This pipeline can run:

• locally
• in CI pipelines
• as scheduled migration jobs

Incremental runs allow safe iteration.

Common Pitfalls

Embedded scripts or inline styling

Magento content often contains presentation-specific markup:

<span style="color:red">Important</span>

Best practice:

• strip inline styling
• move presentation decisions to frontend components

Inconsistent HTML structure

WYSIWYG editors produce inconsistent markup:

• nested paragraphs
• unnecessary spans
• invalid tags

Transformation scripts should normalize markup before conversion.

URL rewrites

Magento may include legacy URL rewrites.

Migration should preserve:

• SEO-friendly URLs
• redirect mappings
• canonical references

Plan redirects early to avoid SEO impact.

Mixed content responsibilities

Magento pages often combine:

• layout
• styling
• content
• configuration

Storyblok encourages separation of concerns through components.

Recommended Migration Strategy

1. define Storyblok component schema
2. export small Magento sample
3. build transformation logic
4. validate rendering in frontend
5. iterate on component structure
6. run bulk migration
7. perform QA checks
8. configure redirects
9. publish content

Iterative validation significantly reduces risk.

Benefits of Decoupling Content from Commerce

After migration, teams often gain:

• reusable marketing components
• faster landing page creation
• cleaner separation of concerns
• improved performance with modern frontend frameworks
• easier experimentation and personalization

Storyblok becomes the content hub, while commerce logic remains in Magento or another commerce engine.

Final Thoughts

Migrating from Magento to Storyblok is not just a platform change — it is an opportunity to improve content structure and editorial workflows.

A thoughtful transformation approach enables long-term flexibility and reduces future rework.

Well-structured content is easier to maintain, reuse, and deliver across channels.

Next Steps

When planning a Magento to Storyblok migration:

• start with component modeling
• build repeatable transformation scripts
• validate content structure early
• automate asset migration
• implement incremental migration workflows

A structured migration approach ensures a smooth transition to a modern headless architecture.