vtex-io-storefront-theme-versioning

What this skill does

# Storefront Theme Versioning, Install, and Rollback

## When this skill applies

Use this skill whenever the version of a content-holding storefront app (a theme such as `vendor.store-theme`, or any app that ships `store/blocks.json`, `store/routes.json`, `store/templates/`, or `store/contentSchemas.json`) is about to change in `master`.

- Bumping the version of a theme app with `vtex release patch | minor | major`
- Running `vtex publish` / `vtex deploy` on a theme app
- Running `vtex install [email protected]` against a production account
- Promoting a workspace that has a different theme version installed than `master`
- Planning recovery from a deploy that "lost" all storefront content
- Reviewing a developer's deploy script that touches a storefront theme

Do not use this skill for:

- block registration via `interfaces.json` — use `vtex-io-render-runtime-and-blocks`
- shopper-facing component code under `react/` — use `vtex-io-storefront-react`
- app-level settings under `manifest.json#settingsSchema` — use `vtex-io-app-settings`
- Master Data schema versioning — use `vtex-io-masterdata-strategy`

## Decision rules

- Treat any app that ships content under `store/` (theme apps and many storefront apps) as a **content-holding app**. Its installed MAJOR version is part of the key the platform uses to store and look up every Site Editor change a merchant has ever saved against blocks declared by that app.
- Site Editor content, custom routes, templates, and per-template render caches are stored by `vtex.pages-graphql` under keys of the form `[email protected]:template`. Examples: `[email protected]:store.home`, `[email protected]:store.product`.
- A `patch` (`0.0.61` → `0.0.62`) and a `minor` (`0.1.0` → `0.2.0`) reuse the same key and the new version sees the same merchant content. A `major` (`0.x` → `5.x`) changes the key. The new major starts with **zero merchant content** even if the theme code is otherwise identical.
- When `vtex.pages-graphql` cannot find content for the active major, it falls back to the default `vtex.store-theme` content. The site visibly degrades to "VTEX default theme" content even though the customer's app is installed and rendering.
- Avoid `vtex release major` on a content-holding app whenever possible. Prefer keeping changes within the current major as `patch` or `minor` so merchant content carries forward automatically.
- When a major bump is unavoidable because of a structural change to blocks, routes, or templates, **migrate the merchant content from the old major to the new major** with the `updateThemeIds` mutation in `[email protected]` before promoting. The mutation rekeys all Site Editor edits, Pages, and Redirects from `vendor.app@{oldMajor}.x` to `vendor.app@{newMajor}.x` in one operation. This is the official developer-accessible recovery surface; do not assume content has to be re-authored manually.
- Always install and validate a new theme major in a **production-flag dev workspace** (`vtex use rollout-workspace --production`, which both creates and switches to the workspace in one step) before promoting. Linking is not enough: `vtex link` does not exercise published artifacts and does not produce the same content-key behavior as `vtex install` + `vtex workspace promote`.
- Run `updateThemeIds` against `[email protected]` from the GraphQL Admin IDE (`vtex install [email protected]`, then `vtex browse admin/graphql-ide`) inside the production-flag dev workspace, after `vtex install` of the new major and before `vtex workspace promote`. Site Editor, Pages, and Redirects in that workspace will then resolve under the new major and be carried with the workspace at promote time.
- Treat `vtex workspace promote` as the atomic cutover. Smoke-test the dev workspace's full page set (home, PDP, PLP, department, search, custom routes, account, checkout entry) after running `updateThemeIds`. If the dev workspace is broken, master will be broken.
- Verify that the version published to the Apps Registry matches the source you expect. A common failure pattern is publishing a stripped-down boilerplate by mistake — the registry version installs cleanly, but it does not contain the custom blocks the existing Site Editor content references. `updateThemeIds` cannot fix a missing-block problem; it only rekeys existing content.
- The same `updateThemeIds` step is required when **downgrading** to a previous major (for example `5.x` → `4.x`). The mutation moves content in either direction across MAJOR boundaries.
- `vtex workspace promote` does **not** wipe master's `vtex.pages-graphql` VBase content. The service merges with `MineWinsConflictsResolver`: a 3-way merge of `base` (the master state the dev workspace forked from), `master` (current master), and `mine` (the dev workspace). Master keys not touched by the dev workspace are preserved; conflicting keys are resolved in favor of the dev workspace ("mine wins"). Plan the rollout so that conflicting writes to master during the rollout window are minimized — for example, by pausing merchant Site Editor edits in master while the dev workspace is being prepared.
- Whenever `MineWinsConflictsResolver` resolves a conflict in production, `vtex.pages-graphql` automatically writes a per-minute snapshot of `base`, `master`, and `mine` to a sibling `userData_backup` VBase bucket. This is logged with `subject: "conflicts_resolution"` in the `io_vtex_logs` index. The snapshot is the recovery source if a promote merges in something unwanted; it is **not** a substitute for the smoke-test step (no backup is written when there is no conflict to resolve). Treat the backup as a safety net for VTEX support escalations, not a routine self-service restore.

## Hard constraints

### Constraint: Major version bumps on content-holding apps require an `updateThemeIds` migration before promote

A `vtex release major` (or any version change that crosses the `MAJOR.x` boundary) on an app that owns Store Framework content MUST NOT be promoted to `master` without first migrating merchant content from the old major to the new major in a production-flag dev workspace, using the `updateThemeIds` mutation in `[email protected]`. The new major starts empty from `vtex.pages-graphql`'s point of view; promoting it to `master` without running `updateThemeIds` makes the storefront fall back to default theme content for every page that depended on Site Editor edits.

**Why this matters**

`vtex.pages-graphql` keys every merchant-owned route, template, Site Editor edit, and Page/Redirect entry by `[email protected]:template`. A patch and minor bump preserve the key; a major bump invalidates it. After a major bump, every Site Editor change the merchant ever saved is no longer visible to the resolver under the new major, and the storefront falls back to default `vtex.store-theme` content. The official developer-accessible fix is the `updateThemeIds` mutation, which rekeys all Site Editor edits, Pages, and Redirects from the old major to the new one in a single operation. Skipping it (or assuming developers must re-author content manually) leaves the storefront degraded for shoppers.

**Detection**

Before running any `vtex install [email protected]` on a production account, compare `X` to the major currently installed (`vtex ls --production | grep store-theme`). If `X` differs, STOP. Require the `updateThemeIds` migration to be executed in a production-flag dev workspace, after the new major is installed and before promote.

Also STOP if a developer is about to run `vtex release major` on an app that ships any of: `store/blocks.json`, `store/routes.json`, `store/templates/`, `store/contentSchemas.json`. Confirm the structural change cannot be modeled as a `patch` or `minor` first; if the major is unavoidable, plan the `updateThemeIds` step explicitly.

**Correct**

```bash
vtex use theme-rollout --production            # creates and switches to a production-flag dev workspace
v