vtex-io-storefront-theme-versioning

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 vendor.store-theme@X.Y.Z 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 vendor.app@MAJOR.x:template. Examples: acme.store-theme@0.x:store.home, acme.store-theme@0.x: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 vtex.pages-graphql@2.x 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 vtex.pages-graphql@2.x from the GraphQL Admin IDE (vtex install vtex.admin-graphql-ide@3.x, 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 vtex.pages-graphql@2.x. 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 vendor.app@MAJOR.x: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 vendor.app@X.Y.Z 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

vtex use theme-rollout --production            # creates and switches to a production-flag dev workspace
vtex install acme.store-theme@5.0.0
vtex install

Wrong

Constraint: Never install a content-holding app version directly to master without a dev-workspace smoke test

Any change that swaps the installed version of a content-holding app on master MUST go through a production-flag dev workspace first (vtex use $name --production), be smoke-tested across the full page set, and then be promoted with vtex workspace promote.

Why this matters

master is the public storefront. Installing a theme directly to master makes the new version live for every shopper instantly. If the install reveals a missing block, an empty content surface under the new major, or a stripped-down published artifact, the only recovery is rollback under load. A production-flag dev workspace renders against the same data as master and surfaces the same failures without exposing shoppers.

Detection

If a developer's command sequence runs vtex install while the active workspace is master, STOP. Require switching to a production-flag dev workspace first.

Correct

Wrong

Constraint: Verify the published artifact matches the source you expect

Before installing a new published version of a content-holding app to master, confirm that the artifact in the Apps Registry actually contains the blocks the active merchant content references. A successful vtex publish does not guarantee the artifact carries the merchant's customizations.

Why this matters

A common failure pattern is publishing from a stripped-down repository or from a base-theme fork that lost the custom blocks the merchant has been editing for months. The install succeeds, but pages-graphql cannot resolve the blocks referenced in the merchant's stored content, and the storefront falls back to default content. The artifact and the content disagree.

Detection

If the published version was built from a repository that does not contain the custom blocks the active theme references, STOP. Republish from the correct source. The updateThemeIds migration only rekeys content; it cannot resolve missing block IDs, so a stripped-down artifact will still fall back to default content even after a successful migration.

Correct

Wrong

Constraint: Treat vtex workspace promote as a 3-way mine-wins merge of pages-graphql VBase, not a wipe

vtex workspace promote MUST be planned as a merge between the dev workspace and master, not as a destructive replacement of master's vtex.pages-graphql VBase content. The service uses MineWinsConflictsResolver from @vtex/api: it diffs base (the master state the dev workspace forked from), master (current master), and mine (the dev workspace), and resolves conflicts in favor of the dev workspace.

Why this matters

Master keys that the dev workspace never touched are preserved on promote. Conflicting keys (something edited in both master and the dev workspace after the fork point) are overwritten by the dev workspace's value. Two practical consequences for a theme rollout:

1. If merchants continue to edit Site Editor in master while the dev workspace is being prepared, those edits to keys the dev workspace also touches will be lost on promote.
2. After updateThemeIds runs in the dev workspace, the dev workspace owns the new-major content map; promoting it cleanly transfers the rekeyed Site Editor edits, Pages, and Redirects into master via mine-wins.

In production, every conflict resolution writes a per-minute snapshot of base, master, and mine to the sibling userData_backup VBase bucket inside vtex.pages-graphql, logged with subject: "conflicts_resolution". No backup is written when there is no conflict to resolve, so smoke-testing remains the primary safety net.

Detection

If a rollout plan assumes promote will "replace" master content, STOP and rephrase as a merge plan: which keys does the dev workspace touch, which keys is master likely to touch in the same window, and how will conflicts be reconciled. If merchants are actively editing Site Editor in master during the rollout window, STOP and either pause those edits, narrow the rollout window, or document which keys will be overwritten.

Correct

Wrong

Preferred pattern

Recommended deploy flow for any change to a content-holding app installed on master:

Recommended emergency rollback after a broken major install on master:

Recommended way to think about content-key behavior:

Common failure modes

• Running vtex release major on a theme to "clean up" the version number, not realizing it requires the updateThemeIds migration before promote.
• Installing a new theme major directly on master because the dev workspace "looked the same".
• Publishing from a forked repository that does not contain the custom blocks the active theme depends on. updateThemeIds rekeys content but cannot resolve missing block IDs.
• Treating vtex link as equivalent to vtex install for content-holding apps. link does not exercise the published artifact resolution path or the major-keyed content lookup.
• Running vtex workspace promote from a workspace that was never smoke-tested end-to-end.
• Promoting a major bump without running updateThemeIds first, so the storefront goes live with default vtex.store-theme content for every page that previously depended on Site Editor edits.
• Reaching for a non-existent vtex workspace create command. The CLI creates a workspace as a side effect of vtex use {workspaceName} --production; that single command both creates and switches.
• Replacing the literal x in updateThemeIds arguments with a minor or patch number (acme.store-theme@5.0.0 instead of acme.store-theme@5.x). The mutation requires the major-with-x form and silently no-ops otherwise.
• Running updateThemeIds against the wrong app in the GraphQL IDE dropdown. The mutation only exists in vtex.pages-graphql@2.x.
• Trusting the public domain to confirm a fix immediately after promotion. CloudFront serves stale content; use ?utm_source=<value> or another cache-busting parameter to bypass the edge during validation.
• Forgetting that downgrades (for example 5.x → 4.x) also cross a MAJOR boundary and need their own updateThemeIds run before promote.
• Assuming vtex workspace promote wipes master vtex.pages-graphql VBase content and re-fills it from the dev workspace. It does not — it 3-way merges with mine-wins, so master keys not touched by the dev workspace survive, and master keys that are also touched by the dev workspace get overwritten silently. Coordinate the rollout window with merchant ops to avoid losing concurrent Site Editor edits in master.
• Treating the userData_backup bucket inside vtex.pages-graphql as a routine restore endpoint. It is only written when conflicts are resolved (no conflict, no backup), it requires admin-level auth and the VBase v2 API, and it is a support-led TROUBLESHOOTING surface — not a substitute for smoke-testing or for the updateThemeIds flow.

Review checklist

• Is the proposed version bump correctly classified as patch, minor, or major against SemVer rules?
• If the bump crosses a major boundary, is there a documented updateThemeIds migration step in the production-flag dev workspace (in either direction, including downgrades)?
• Is the install going to a production-flag dev workspace first (vtex use $name --production), never directly to master?
• If the bump is major, has updateThemeIds been run against vtex.pages-graphql@2.x from the GraphQL Admin IDE, and has the response been { "updateThemeIds": true }?
• Has the published artifact been verified to contain the custom blocks the active theme depends on?
• Has the dev workspace been smoke-tested across home, PDP, PLP, department, search, custom routes, account, checkout entry, and the Storefront module (Site Editor, Pages, Redirects)?
• Has the rollout window been coordinated so that no concurrent Site Editor edits land on master between the dev workspace's updateThemeIds and vtex workspace promote, given the 3-way mine-wins merge?
• After promote, has io_vtex_logs been checked for a subject: "conflicts_resolution" entry on vtex.pages-graphql for this account, and (if present) have the listed userData_backup paths been recorded for support escalation?
• Is the dev workspace retained for at least one business day after promotion in case a fast re-promote is needed?

Related skills

• vtex-io-app-contract — When the question is what the manifest contract should declare, and why a major version bump is a contract-breaking change for content-holding apps.
• vtex-io-storefront-theme-app — When the question is what a theme app actually owns (store/blocks.json, store/routes.json, page templates) and how those files relate to merchant Site Editor content.
• vtex-io-render-runtime-and-blocks — When the question is how a block name in a theme resolves to a React component, and why missing blocks under the active major cause render failures.
• vtex-io-data-access-patterns — When the question is whether a piece of data should live behind Site Editor at all, or in app settings, Master Data, or another store.

Reference

• Manifest — How vendor, name, and version form the app identity used in storefront content keys.
• Versioning an App — vtex release and the SemVer rules that decide whether a bump preserves or invalidates downstream content keys.
• Publishing an App — How vtex publish produces the artifact installed by vtex install.
• Installing an App — Workspace scope of vtex install and why dev workspaces must be production-flag for realistic testing.
• Creating a Production Workspace — vtex use {workspaceName} --production is the single command that both creates and switches to a production-flag workspace.
• Promoting a Workspace to Master — vtex workspace promote as the atomic cutover from a production-flag dev workspace to master.
• Migrating CMS settings after a major theme update — Official procedure for the updateThemeIds mutation in vtex.pages-graphql@2.x, including the GraphQL IDE setup and the literal MAJOR.x argument format.
• vtex/pages-graphql TROUBLESHOOTING.md — How MineWinsConflictsResolver writes per-minute base, master, and mine snapshots into the userData_backup bucket of vtex.pages-graphql and how to fetch them via the VBase v2 API for support-led recovery (internal VTEX repo).
• Store Framework — Why theme apps own store/ content and how Store Framework consumes it at render time.