Skip to content

Latest commit

 

History

History

storyblok

README.md

@b10cks/migrate-storyblok

Storyblok to b10cks migration tooling for teams that need more than a one-off export.

This package ships both a CLI and a library API for migrating Storyblok spaces into b10cks. It is designed to be rerunnable, source-aware, and practical for real migration projects where you iterate, validate, re-run, and reconcile before cutover.

What It Migrates

The current adapter supports all of the following:

  • Asset folders, preserving hierarchy and storing Storyblok IDs in external_id
  • Assets, including folder mapping, tags, translated metadata, and focus-point normalization
  • Datasources and datasource entries, with reconciliation by external_id, slug, and logical key
  • Storyblok components into b10cks blocks, including folders, tags, datasource-backed options, nested block fields, references, assets, links, richtext, meta fields, and sb-price
  • Stories into b10cks content with parent-child relationships, block resolution, localized overlays, and optional publish reconciliation
  • Interactive CLI usage and programmatic usage through exported migrator classes

Operational Model

This package is built around safe reruns:

  • Existing b10cks records are matched using external_id wherever possible.
  • Content migration runs in two passes: first upserting primary records, then reconciling references, hierarchy, and optional publish state.
  • Delta sync is built in for content. Without --force, older or unchanged stories are skipped instead of overwritten.
  • Missing Storyblok assets referenced from content can be uploaded on demand during content migration.

Installation

Install from npm when published:

pnpm add @b10cks/migrate-storyblok

Local development from the monorepo:

pnpm install
pnpm build

Prerequisites

You will typically need:

  • A Storyblok management token
  • A numeric Storyblok space ID
  • A b10cks management token
  • A b10cks space ID or slug, depending on your environment

The package expects Node >=24.7.0 in this repository.

Quick Start

Generate a local environment template:

b10cks-migrate-storyblok init-env > .env.local

Validate credentials before a run:

b10cks-migrate-storyblok validate

Generate a reusable Storyblok story cache:

b10cks-migrate-storyblok cache-stories \
  --storyblok-token YOUR_STORYBLOK_TOKEN \
  --storyblok-space-id 123456 \
  --story-cache-dir ./.storyblok-cache \
  --backup-story-cache

Start an interactive migration:

b10cks-migrate-storyblok migrate

Run a non-interactive migration:

b10cks-migrate-storyblok migrate \
  --storyblok-token YOUR_STORYBLOK_TOKEN \
  --storyblok-space-id 123456 \
  --b10cks-token YOUR_B10CKS_TOKEN \
  --b10cks-space-id your-space-id \
  --asset-folders \
  --assets \
  --datasources \
  --datasource-entries \
  --blocks \
  --content

Recommended Run Order

The CLI lets you run any subset of migrators, but the most reliable production sequence is:

  1. asset-folders
  2. assets
  3. datasources
  4. datasource-entries
  5. blocks
  6. content

That order ensures referenced folders, assets, datasources, and blocks exist before content translation begins.

CLI Commands

Command Purpose
migrate Runs one or more Storyblok-to-b10cks migration stages, either interactively or fully scripted
cache-stories Fetches Storyblok stories into a reusable local JSON cache directory
validate Checks that the provided credentials can be resolved and that Storyblok access works before a migration run
init-env Prints a ready-to-fill environment template for local setup

migrate

Runs one or more migration stages.

Option Description
--storyblok-token <token> Storyblok management token. Overrides STORYBLOK_TOKEN when provided on the command line.
--storyblok-space-id <spaceId> Numeric Storyblok space ID. Accepts the direct ID instead of prompting or reading STORYBLOK_SPACE_ID / STORYBLOK_SPACE.
--b10cks-token <token> b10cks management token. Overrides B10CKS_TOKEN when provided on the command line.
--b10cks-space-id <spaceId> Target b10cks space identifier used for all writes. Overrides B10CKS_SPACE_ID / B10CKS_SPACE.
--b10cks-base-url <url> Custom b10cks API base URL. Useful for non-production environments or local API targets.
--config-file <path> JSON file used by content migration for last_migrated cutoffs and post-translation field mapping rules.
--mapping-file <path> Deprecated alias for --config-file. Keep only for backward compatibility.
--force Forces content writes even when delta-sync logic would normally skip unchanged or newer b10cks entries.
--publish Publishes migrated content variants during the reconciliation pass when the source Storyblok story is considered published.
--verbose Enables deeper debug logging, including payload dumps for 422 b10cks content write failures.
--story-cache-dir <path> Directory used to read or write cached Storyblok stories.
--reuse-story-cache Reads Storyblok stories from --story-cache-dir during content migration instead of fetching them from Storyblok.
--write-story-cache Writes fetched Storyblok stories to --story-cache-dir during content migration.
--backup-story-cache When writing a cache, also writes a timestamped story snapshot into backups/.
--asset-folders Runs only the asset-folder migrator. Use before assets to preserve folder hierarchy.
--assets Runs only the asset migrator. Preserves external_id, folder assignments, metadata, and tags.
--blocks Runs the block migrator that translates Storyblok components into b10cks block definitions.
--content Runs the content migrator with two-pass reconciliation, localization handling, and optional publish behavior.
--datasources Runs only the datasource migrator, creating or updating datasource definitions in b10cks.
--datasource-entries Runs only the datasource-entry migrator, reconciling entries under their resolved target datasources.

If no migration flags are provided, the CLI falls back to an interactive checklist.

cache-stories

Fetches Storyblok stories, including hydrated content payloads, and stores them in a local directory:

  • stories.json contains the normalized story array used by the content migrator.
  • manifest.json records the cache format version, generation time, Storyblok space ID, and story count.
  • backups/stories.<timestamp>.json is created when --backup-story-cache is used.

You can then run content migration from the cache:

b10cks-migrate-storyblok migrate \
  --storyblok-token YOUR_STORYBLOK_TOKEN \
  --storyblok-space-id 123456 \
  --b10cks-token YOUR_B10CKS_TOKEN \
  --b10cks-space-id your-space-id \
  --content \
  --story-cache-dir ./.storyblok-cache \
  --reuse-story-cache

Or write/update the cache as part of a live content migration:

b10cks-migrate-storyblok migrate \
  --storyblok-token YOUR_STORYBLOK_TOKEN \
  --storyblok-space-id 123456 \
  --b10cks-token YOUR_B10CKS_TOKEN \
  --b10cks-space-id your-space-id \
  --content \
  --story-cache-dir ./.storyblok-cache \
  --write-story-cache \
  --backup-story-cache
Option Description
--storyblok-token <token> Storyblok management token. Overrides STORYBLOK_TOKEN when provided on the command line.
--storyblok-space-id <spaceId> Numeric Storyblok space ID. Accepts the direct ID instead of prompting or reading STORYBLOK_SPACE_ID / STORYBLOK_SPACE.
--story-cache-dir <path> Required output directory for stories.json and manifest.json.
--backup-story-cache Writes a timestamped story snapshot into backups/ in addition to the reusable stories.json.

validate

Prompts for or reads credentials, then validates connectivity.

Option Description
--storyblok-token <token> Storyblok management token used for the validation request.
--storyblok-space-id <spaceId> Numeric Storyblok space ID to validate against.
--b10cks-token <token> b10cks management token to resolve from CLI or environment before validation.
--b10cks-space-id <spaceId> b10cks space identifier to resolve from CLI or environment before validation.

Current behavior:

  • Storyblok validation is implemented and performs a real API check against the configured space.
  • Full b10cks validation is not yet implemented in the CLI, so this command should be treated as a partial preflight check.

init-env

Prints a .env.local template to stdout.

Option Description
None init-env does not accept command-specific flags and always prints the same template structure.

Configuration Sources

Configuration is resolved in this order:

  1. CLI options
  2. Environment variables
  3. .env.local
  4. .env
  5. Interactive prompts for any missing required values

Supported environment variables:

STORYBLOK_TOKEN=your_storyblok_token_here
STORYBLOK_SPACE_ID=123456
# Optional alias form if your environment stores structured values
# STORYBLOK_SPACE={"id":123456}

B10CKS_TOKEN=your_b10cks_token_here
B10CKS_SPACE_ID=your-space-id
# Optional alias form if your environment stores structured values
# B10CKS_SPACE={"id":"your-space-id"}

B10CKS_BASE_URL=https://api.b10cks.com

Content Migration Semantics

Content migration is the most opinionated part of the adapter. A few behaviors are worth understanding before you run it on a live project.

Two-Pass Reconciliation

The content migrator performs two passes:

  1. It loads Storyblok stories, assets, components, space language settings, and existing b10cks content, then upserts the primary content entries.
  2. It rebuilds translation context from the newly resolved records and reconciles references, parent links, overlays, and optional publish state.

This design improves correctness for internal links, references, and parent-child content structures that are hard to resolve in a single pass.

Folder and Startpage Handling

Storyblok folder structures are normalized into b10cks content as follows:

  • Folders without a startpage become synthetic folder content entries backed by a virtual Storyblok folder block.
  • Folder startpages are merged with their parent folder aliases so the resulting b10cks content keeps the expected path identity.
  • Stories are sorted by resolved parent relationship before migration so parents exist before children whenever possible.

Localization

Localized content is split into:

  • A default-language base entry
  • One overlay content entry per detected non-default language

Overlay entries are linked via i18n_parent_id and use external IDs in the form:

<story-id>__i18n__<language>

The migrator also recognizes translated field keys that follow Storyblok-style suffix patterns such as __i18n__ and _i18n_.

Delta Sync and Forced Reconciliation

Without --force, a story is skipped when either of these is true:

  • The story updated_at is not newer than the config file's last_migrated threshold
  • The existing b10cks content updated_at is newer than or equal to the Storyblok story updated_at

Use --force when you intentionally want to override those safeguards during cutover or backfill.

Asset Backfilling During Content Migration

If content references a Storyblok asset that has not yet been migrated, the content migrator will try to:

  1. Discover the referenced Storyblok asset URL or ID
  2. Download the asset from Storyblok
  3. Upload it into b10cks
  4. Continue content translation using the newly resolved asset

If that asset upload fails, the migration continues, logs a warning, and emits a manual-intervention note for the affected story.

Block Translation Coverage

Storyblok component schemas are translated into b10cks block schemas with support for the most important field families, including:

  • text, textarea, markdown, and richtext
  • number, boolean, and datetime
  • asset and multiasset
  • bloks
  • Single and multi option fields
  • Datasource-backed option fields
  • Internal story references
  • Link fields, including asset links and mailto handling
  • Table fields
  • Custom meta-fields
  • Custom sb-price

When datasource-backed fields are present, the block migrator resolves Storyblok datasource slugs to existing b10cks datasource IDs so the resulting schema remains connected.

Content Mapping Config

The content migrator accepts a JSON config file through --config-file that can define:

  • last_migrated for delta-sync cutoffs
  • Content field remapping rules applied after Storyblok-to-b10cks translation

The adapter accepts three mapping styles:

  • Block-scoped mappings
  • Global flat mappings
  • An array of explicit { from, target, override } entries

Block-Scoped Example

{
  "last_migrated": "2026-04-12T00:00:00.000Z",
  "mapping": {
    "page": {
      "content.ogImage": { "target": "content.meta.ogImage", "override": true },
      "content.pageTitle": { "target": ["name", "content.meta.title"], "override": false },
      "content.canonical": { "target": "content.meta.canonical", "override": true }
    }
  }
}

Global Flat Example

{
  "content.pageTitle": ["name", "content.meta.title"],
  "content.canonical": "content.meta.canonical"
}

Explicit Array Example

[
  {
    "from": "content.pageTitle",
    "target": ["name", "content.meta.title"],
    "override": false
  }
]

Mapping behavior:

  • target may be a single path or an array of target paths
  • override: false only writes when the source has a value and the current target is empty
  • When a mapping is applied and the source path is not one of the targets, the source field is removed from the payload

See config.json.example for a minimal example.

Programmatic Usage

import {
  AssetFolderMigrator,
  AssetMigrator,
  BlockMigrator,
  ContentMigrator,
  DataSourceMigrator,
  DataSourceEntryMigrator,
  type MigrationConfig,
} from '@b10cks/migrate-storyblok'

const config: MigrationConfig = {
  storyblokToken: 'your-storyblok-token',
  storyblokSpaceId: 123456,
  b10cksToken: 'your-b10cks-token',
  b10cksSpaceId: 'your-space-id',
  b10cksBaseUrl: 'https://api.b10cks.com',
  configFile: './content-config.json',
  publish: false,
}

const migrator = new ContentMigrator(config, (progress) => {
  console.log(`${progress.current}/${progress.total} ${progress.itemName}`)
})

const result = await migrator.migrate()
console.log(result)

Development

From the repository root:

pnpm install
pnpm --filter @b10cks/migrate-storyblok build
pnpm --filter @b10cks/migrate-storyblok test

Known Limitations

  • CLI validate currently verifies Storyblok access but does not yet perform full b10cks validation.
  • Content publishing only happens when --publish is set and the source story is considered published.
  • Content write validation errors are surfaced from the b10cks API; --verbose is the best way to inspect the payload that caused a 422.