b10cks Migration Monorepo

Migration adapters for bringing content from external CMS platforms into b10cks.

This repository is organized as a pnpm workspace so each source-system adapter can evolve independently while still sharing release tooling, development conventions, and a common operational model. Today the monorepo ships one adapter, Storyblok, with the structure already in place for additional source platforms.

Why This Repo Exists

The migration tooling in this monorepo is built for real, repeatable migrations rather than one-off export scripts:

• Source records are tracked in b10cks via external_id, so reruns reconcile instead of blindly duplicating data.
• Content migration is source-aware, translating CMS-specific structures into b10cks blocks, content, assets, and data sources.
• Migrations are designed to be staged and rerunnable, which is critical for dry runs, cutovers, and incremental syncs.
• Operators can work interactively through the CLI or compose migrations programmatically from the library API.

Workspace Layout

migration/
├── package.json
├── pnpm-workspace.yaml
└── packages/
    └── storyblok/
        ├── README.md
        ├── config.json.example
        └── src/

Packages

Package	Status	Purpose
@b10cks/migrate-storyblok	Active	Migrates Storyblok asset folders, assets, blocks, content, datasources, and datasource entries into b10cks

Current Capabilities

The Storyblok adapter currently supports:

• Asset folder migration with preserved hierarchy and external_id tracking
• Asset migration with folder mapping, tag preservation, translated metadata, and focus-point normalization
• Datasource and datasource-entry migration with slug-aware reconciliation
• Block migration from Storyblok components, including tags, folders, datasource-backed options, references, and nested block schemas
• Content migration with two-pass reconciliation, localized overlays, delta sync, and optional publish behavior
• CLI-based operation plus programmatic access to all migrators

Getting Started

Install dependencies from the repository root:

pnpm install

Build the published package(s):

pnpm build

Run the full test suite:

pnpm test

Run linting and formatting:

pnpm lint
pnpm format

Recommended Migration Workflow

For a real Storyblok project, the safest sequence is:

1. Validate credentials and environment setup.
2. Migrate structural dependencies first: asset folders, assets, datasources, datasource entries, and blocks.
3. Migrate content after referenced assets, blocks, and data sources exist in b10cks.
4. Re-run content with --force or a refined config file if you need to override delta-sync safeguards during cutover.

The Storyblok adapter is intentionally rerunnable. Existing b10cks records are matched by external_id and, for content, also reconciled by resolved slugs and hierarchy when possible.

Monorepo Scripts

The root workspace exposes the commands you will use most often:

• pnpm build builds the workspace packages
• pnpm test runs package tests
• pnpm lint runs oxlint
• pnpm format runs oxfmt --write
• pnpm clean removes package build artifacts
• pnpm changeset manages versioning metadata

Developing New Adapters

The monorepo is structured so each source adapter can provide:

• A focused CLI entrypoint
• Source and target service clients
• Translators from source concepts to b10cks entities
• Migrators for each domain object
• Package-scoped documentation and examples

That keeps source-specific complexity inside each package while preserving a consistent operator experience across adapters.

Package Documentation

The adapter-specific README is the operational guide for running migrations:

• Storyblok: packages/storyblok/README.md