Skip to content

Migrating legacy variant-container content

The variant-container migration reports by default and writes only with --apply, refusing any placement that is nested or linked to a saved component.

You need this on one kind of database: a site whose stored layouts predate the module variant container, and so still carry deprecated variantContainer modules where a moduleVariantContainer column node belongs. The command rewrites those documents in place. It reports and writes nothing until you pass --apply; --dry-run is a synonym for the default, kept so a script can say what it means.

bash
# 1. Report. Nothing is written; a "Nothing was written" line says so near the
# end — the actual last line if the exit code is 0, but an "Exiting 2:" or
# "Exiting 1:" line follows it whenever something was refused or skipped.
pnpm exec kywi upgrade:variant-containers

# 2. Write, keeping the before-layouts somewhere you will still find them later.
pnpm exec kywi upgrade:variant-containers --apply --backup ./kywi-vc-backup-0.23.0.json

Scope it with --site <slug|uuid>, --content <uuid> or --node <moduleId>. --node is the point of the design: migration is owner-invoked per placement rather than forced, so one module can move while the rest of the site waits. --json gives the whole report as a machine-readable object, and --config points at a kywi.config.ts that is not in the working directory. A scan that matches nothing prints No legacy variantContainer modules found. The scan covers section templates as well as pages: a row sourced from a saved section template (a blueprint, not a specific page) prints with a trailing [blueprint] tag instead of the usual [<status>], so you can tell the two shapes apart in the report before deciding what to do with either.

The backup is the only copy of what you overwrite

Without --backup the run still writes one, to ./kywi-vc-backup-<timestamp>.json — but only once there is at least one document to write; a run with nothing writable (everything refused, or held by an open changeset) creates no backup file at all, --backup or not. For a page or other content row it is written before that row is touched, and it holds the layout read back under the row lock — not the one the scan saw a moment earlier, so a concurrent editor save between scan and write cannot leave you holding a file that restores the wrong document while looking like a working restore. A section template (blueprint) is different: its definition is locked inside the write call itself, so its backup entry is the definition the scan read, not a locked re-read. The file is opened exclusively, so a second run pointed at the same path fails instead of truncating the first run's evidence:

text
Backup file <path> already exists — refusing to overwrite it. Move it aside, or pass --backup <path> with a name that is free.

Two refusals, and neither one is a failure

A refused placement is reported and left exactly as it is, so the rest of the document still migrates. Both refusals exist because converting would be worse than not converting.

text
REFUSED — sits inside a section-level variantContainer arm — module containers never nest; move it out of the personalized band first
REFUSED — is linked to a saved component — its arms live in the component definition; detach the instance first

The first would produce a document that fails layout validation, which would skip — and so block — the whole page. The second reads its props from the component definition rather than the node, so converting from the node's own props would silently build a container with no arms. Clear them by hand first: move the module out of the personalized band, or detach the instance (Living with linked components), then re-run.

Exit codes, and the skip you will actually hit

0 is clean. 2 means placements were refused and need a decision. 1 means something you asked for did not happen — a document was skipped, or a scoping flag matched nothing — and 1 wins over 2 when both apply, so a script branching on the exit code sees the more severe outcome. The skip you will meet in practice is a document an open changeset is holding:

text
SKIPPED — held by open changeset(s) <names> — publishing one would re-introduce the legacy shape from its version snapshot. Publish it first, then re-run, or pass --ignore-open-changesets.

That snapshot is the whole reason: publishing the changeset later would put the legacy modules back. Publish or discard it first (Batching and publishing with changesets) rather than reaching for --ignore-open-changesets.

For scale: this project's own 0.15.0 upgrade found two legacy placements across the whole site, migrated both, and kept the backup file in the repo root. If your report is much longer than that, run it per site.