Migrate from Storyblok
Move a Storyblok space to CMS Orbit: how stories, blocks, folders and languages map, datasources as taxonomies from their CSV, reading every story with the Content Delivery API, turning blocks, rich text, assets, links and relations into an import file, and importing it with redirects.
How-to guide10 min read
Storyblok and CMS Orbit both build pages from blocks, so most of a Storyblok space maps across one to one. This guide reads every story with Storyblok's Content Delivery API, turns it into an import file, and imports it with the script from Import content with the Management API. The examples move a Northwilds journal with articles, authors and a Norwegian translation.
For the project around it, from the content inventory to the weeks after launch, see Plan a migration to CMS Orbit.
How Storyblok maps to CMS Orbit
full_slugde/… become the de copies of their counterpartsField types:
texttextarearichtext, or a list of blocksrichtext: convert it to HTML while you transformnumberdate or datetimebooleanselect, multiselect, reference, references or taxonomy, by sourceasset, assetslinkcomponents slotrichtext holding an HTML tableslider, rating (star rating), code (code block) or palette (named brand colours). Otherwise model the data as fieldsBefore you start
- A Storyblok preview access token for the space, to read drafts, from Settings › Access tokens.
- To read the block schema: a Storyblok personal access token for the Management API.
- In CMS Orbit: a space with Staging, a region and every language you need, and a management token. See "Before you start" in Import content with the Management API.
- Node 20 or later.
1List your blocks
Read the space's block definitions from the Management API:
curl -H "Authorization: <personal access token>" \ https://mapi.storyblok.com/v1/spaces/<space id>/componentsFor each block, choose its CMS Orbit counterpart: content type blocks become content types, nestable blocks become components, and Blocks fields become slots with allowedComponents. Write them in a schema.mjs and create them with Schema as code. Keep Storyblok's field names where they read well; renaming now is free, and later it is not.
The script below assumes the journal model from that guide, plus three Storyblok blocks mapped to CMS Orbit components:
rich_text with a text fieldtextgear_grid with title and an items Blocks fieldgearList with heading and an items slotgear_card with name and linkgearItem2Bring datasources across
Each Storyblok datasource becomes a taxonomy, and each entry a term: the entry's name is the term's label and its value the term's value, made into a slug, so Ski touring becomes ski-touring. Do this before importing stories, so option fields that use the datasource find their terms.
- In CMS Orbit, open Schema › Taxonomies and create the taxonomy, such as Activity with the key
activity. - In Storyblok, open the datasource and export it as CSV. Storyblok writes one file per dimension.
- In CMS Orbit, choose Import CSV and pick the default file. The preview shows each term as new; choose Import.
- For each dimension, import its file the same way and choose what
dimension_valuefills. A dimension per language, such asde, becomes that language's labels (German). A dimension per market, such asgermany, becomes the labels in that region (German in Germany).
Terms that don't apply in a market can then be hidden there: open the term, pick the region and turn off Offered in, or add a region:germany:hidden column with yes and import again. A datasource with many entries is quicker as one CSV in CMS Orbit's own format, with a column per language and region; see Tag content with taxonomies. The Management API imports the same files, for scripts that move many datasources.
On the website, replace GET/v2/cdn/datasource_entries?datasource=activity&dimension=de with cms.getTaxonomy({ key: 'activity', region, locale }): value stays what your filters use, and label is what Storyblok called the dimension value.
3Read and transform the stories
Install Storyblok's rich text renderer:
npm install @storyblok/richtextThe script reads every story with the Content Delivery API (GET/v2/cdn/stories, 100 per page, version=draft), once for the main language and once per extra language with language=. It converts each block with BLOCKS and each story with TYPES, and writes import.json. Use the base address for your space's region, such as https://api-us.storyblok.com/v2/cdn for the United States.
import { writeFile } from 'node:fs/promises'import { renderRichText } from '@storyblok/richtext'const API = process.env.STORYBLOK_API ?? 'https://api.storyblok.com/v2/cdn'const TOKEN = process.env.STORYBLOK_TOKENconst LANGUAGES = { nb: 'nb-NO' }async function stories(language) { const all = [] for (let page = 1; ; page += 1) { const params = new URLSearchParams({ token: TOKEN, version: 'draft', per_page: '100', page: String(page) }) if (language) params.set('language', language) const response = await fetch(`${API}/stories?${params}`) if (!response.ok) throw new Error(`Storyblok answered ${response.status}`) const { stories: batch } = await response.json() all.push(...batch) if (all.length >= Number(response.headers.get('total')) || batch.length === 0) return all }}const newUrl = (fullSlug) => `/${fullSlug.replace(/^blog\//, 'journal/')}`const asset = (file) => (file?.filename ? { $asset: { url: file.filename, alt: file.alt ?? '' } } : null)function link(value) { if (!value) return null if (value.linktype === 'story' && value.id) return { $link: value.id } if (value.linktype === 'email') return { kind: 'email', href: value.email } if (value.url) return { kind: 'url', href: value.url.replace(/^https:\/\/northwilds\.com/, '') || '/' } return null}const BLOCKS = { rich_text: (block) => ({ type: 'text', fields: { text: renderRichText(block.text) } }), gear_grid: (block) => ({ type: 'gearList', fields: { heading: block.title }, children: { items: block.items.map(convert).filter(Boolean) }, }), gear_card: (block) => ({ type: 'gearItem', fields: { name: block.name, link: link(block.link) } }),}function convert(block) { const map = BLOCKS[block.component] if (!map) { console.warn(`No mapping for the ${block.component} block`) return null } return map(block)}const TYPES = { author: (story) => ({ type: 'author', fields: { bio: renderRichText(story.content.bio), photo: asset(story.content.photo) }, }), article: (story) => ({ type: 'journalPost', url: newUrl(story.full_slug), fields: { excerpt: story.content.teaser ?? null, cover: asset(story.content.image), author: story.content.author ? { $ref: story.content.author } : null, }, components: (story.content.body ?? []).map(convert).filter(Boolean), }),}const main = await stories()const translated = Object.fromEntries( await Promise.all(Object.keys(LANGUAGES).map(async (code) => [code, await stories(code)])),)const entries = main .filter((story) => TYPES[story.content.component]) .map((story) => { const translations = {} for (const [code, list] of Object.entries(translated)) { const other = list.find((item) => item.uuid === story.uuid) if (!other || JSON.stringify(other.content) === JSON.stringify(story.content)) continue const { fields, components } = TYPES[story.content.component](other) translations[LANGUAGES[code]] = { fields, ...(components?.length ? { components } : {}) } } return { key: story.uuid, name: story.name, slug: story.slug, ...TYPES[story.content.component](story), translations } })await writeFile('import.json', JSON.stringify({ environment: 'staging', region: 'europe', locale: 'en-GB', translations: Object.values(LANGUAGES), entries, redirects: main .filter((story) => story.content.component === 'article') .map((story) => ({ from: `/${story.full_slug}`, to: newUrl(story.full_slug) })),}, null, 2))console.log(`Wrote ${entries.length} entries to import.json`)export STORYBLOK_TOKEN=<preview token>node storyblok.mjsWhat it does with the parts that need thought:
- Blocks map one to one. A block without a mapping is left out with a warning, so you see what is missing.
- Nested blocks go in
childrenunder the slot's key, as CMS Orbit stores them. - Rich text becomes HTML with
renderRichText. Blocks embedded in rich text and images in it are removed when CMS Orbit saves it, so move them into blocks if your stories use them. - Links: a link to a story becomes a link to its new entry, by the story's
uuid. A link to your own domain becomes a plain address on the site. - Relations: an option field holding a story's
uuidbecomes a$refto it. - Languages: for field-level translation, the script asks for each language and keeps the fields that differ. For folder-level translation, read the
de/…stories instead, and attach each to its main story through the story'salternates. - Alt text: Storyblok has one alt text per asset. Add the other languages' alt text in the import file, or in the media library before publishing.
- Addresses:
newUrlmovesblog/…to/journal/…, andredirectslists each old address.
4Import
Check the file with a dry run, then run the import, with cms-orbit from Import content with the Management API:
npx cms-orbit import import.json --dry-runnpx cms-orbit import import.jsonCheck the entries in CMS Orbit on Staging, then run it again with --publish, or publish them in CMS Orbit. Promote them to Production with their redirects as described in Plan a migration.
5Switch the website
- Register your existing block components under the new component keys. With the SDK, a component gets
blockwith its fields, and nested blocks asblock.itemsor throughCmsBlocks. See Render components. - Replace
storyblok-js-clientor@storyblok/reactcalls with the SDK:cms.resolve({ path })for a page. See Connect a website. - Replace the Storyblok bridge with CMS Orbit's live preview, and mark blocks with
data-cms-idso editors can click them. See Set up the live preview. - Point webhooks at your website. See Webhooks.
- Promote the content to Production, deploy, and check that old addresses redirect.
What does not come across
- Story history and versions. Each entry starts with one draft.
- Scheduled releases, comments and workflow stages. Set them up again in CMS Orbit.
- Field plugins. Sliders, star ratings, code blocks and colour palettes are field types of their own:
slider,rating,codeandpalette. Model any other plugin's data with CMS Orbit's field types. - Roles and users. People sign in with Orbit and get roles in CMS Orbit.
Was this page helpful?