docs menu

Migrate from Storyblok

The Storyblok source reads stories from the delivery API, in every language, both published and draft with a preview token. With a Management API token it also reads your components, so the schema matches your space exactly; without it, the schema is inferred from the content.

Import#

bash
galerne import --from storyblok --source-token <preview-token> --management-token <token> --space 123456 --dry-run
galerne import --from storyblok --source-token <preview-token> --management-token <token> --space 123456

Options go after --from as flags in kebab case (projectId is --project-id). With the import_from tool, they go in options. See the migration overview for the shared flags, the report and re-runs.

OptionWhat it is
tokenA delivery token. A preview token also reads drafts. On the CLI: --source-token
managementTokenA Management API token, to read the components (needs space)
spaceThe space id
regioneu (default), us, ap, ca or cn
languagesLanguage codes, the default first. Default: read from the space
file, dataA bundle { components, languages, stories, translations } instead of the API, such as one a Galerne export wrote

How content maps#

StoryblokGalerne
Content type of a story (content.component)Document type
Story uuidDocument id
Story slugslug, unless the content has a slug field
Rich text, Markdown fieldsRich text
Nested bloksblocks, with _uid as the key
Bloks inside rich textEmbeds; the field's allowed components become its embeds
Asset, multi-assetimage or file, blocks of images and files; the focus point becomes the hotspot when the image size is known
Link to a storyreference
Link field mixing stories and URLsA URL string, story links written as their path
Email linkA mailto: URL
Tabletable
Single and multi options of storiesReferences
OptionsStrings
Translatable fieldsLocalized fields

What the import loses#

The report lists each of these when it happens.

  • Section and tab fields are dropped; unknown objects become JSON code fields, with a warning.
  • Folders and stories without content are skipped.
  • Options are dropped from the schema when stored values fall outside them.
  • Folder-level translation is read as field-level: translatable fields become localized.

Export to Storyblok#

bash
galerne export --to storyblok --out ./storyblok-export

The folder holds storyblok.json (the whole bundle, which the importer can read back with --file), components.json, stories.json with draft content to create through the Management API, assets under assets/, and a README.md.

The export loses:

  • Document-level translations have no Storyblok equivalent: each translation becomes its own story, with a warning.
  • The hotspot becomes a one-pixel focus box, and only when the media size is known.
  • title and slug move onto the story's name and slug.
  • Object fields become nested bloks. Embeds become bloks inside rich text, and the field allows their components.