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.
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
This package is built around safe reruns:
- Existing b10cks records are matched using
external_idwherever 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.
Install from npm when published:
pnpm add @b10cks/migrate-storyblokLocal development from the monorepo:
pnpm install
pnpm buildYou 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.
Generate a local environment template:
b10cks-migrate-storyblok init-env > .env.localValidate credentials before a run:
b10cks-migrate-storyblok validateGenerate 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-cacheStart an interactive migration:
b10cks-migrate-storyblok migrateRun 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 \
--contentThe CLI lets you run any subset of migrators, but the most reliable production sequence is:
asset-foldersassetsdatasourcesdatasource-entriesblockscontent
That order ensures referenced folders, assets, datasources, and blocks exist before content translation begins.
| 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 |
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.
Fetches Storyblok stories, including hydrated content payloads, and stores them in a local directory:
stories.jsoncontains the normalized story array used by the content migrator.manifest.jsonrecords the cache format version, generation time, Storyblok space ID, and story count.backups/stories.<timestamp>.jsonis created when--backup-story-cacheis 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-cacheOr 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. |
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.
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 is resolved in this order:
- CLI options
- Environment variables
.env.local.env- 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.comContent migration is the most opinionated part of the adapter. A few behaviors are worth understanding before you run it on a live project.
The content migrator performs two passes:
- It loads Storyblok stories, assets, components, space language settings, and existing b10cks content, then upserts the primary content entries.
- 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.
Storyblok folder structures are normalized into b10cks content as follows:
- Folders without a startpage become synthetic
foldercontent 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.
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_.
Without --force, a story is skipped when either of these is true:
- The story
updated_atis not newer than the config file'slast_migratedthreshold - The existing b10cks content
updated_atis newer than or equal to the Storyblok storyupdated_at
Use --force when you intentionally want to override those safeguards during cutover or backfill.
If content references a Storyblok asset that has not yet been migrated, the content migrator will try to:
- Discover the referenced Storyblok asset URL or ID
- Download the asset from Storyblok
- Upload it into b10cks
- 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.
Storyblok component schemas are translated into b10cks block schemas with support for the most important field families, including:
text,textarea,markdown, andrichtextnumber,boolean, anddatetimeassetandmultiassetbloks- 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.
The content migrator accepts a JSON config file through --config-file that can define:
last_migratedfor 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
{
"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 }
}
}
}{
"content.pageTitle": ["name", "content.meta.title"],
"content.canonical": "content.meta.canonical"
}[
{
"from": "content.pageTitle",
"target": ["name", "content.meta.title"],
"override": false
}
]Mapping behavior:
targetmay be a single path or an array of target pathsoverride: falseonly 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.
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)From the repository root:
pnpm install
pnpm --filter @b10cks/migrate-storyblok build
pnpm --filter @b10cks/migrate-storyblok test- CLI
validatecurrently verifies Storyblok access but does not yet perform full b10cks validation. - Content publishing only happens when
--publishis set and the source story is considered published. - Content write validation errors are surfaced from the b10cks API;
--verboseis the best way to inspect the payload that caused a422.