Skip to main content
affpapa.org
RU EN
skill CX Codex

vtex-io-storefront-theme-versioning — Claude Code skill: setup guide

Guides coding agents through publishing, updating, or rolling back VTEX IO storefront themes without losing merchant Site Editor data across major versions.

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓ 
npx skills add vtex/skills --skill vtex-io-storefront-theme-versioning -a claude-code
Open on GitHub

What vtex-io-storefront-theme-versioning does

The skill governs version transitions for storefront apps holding files under store/. In VTEX IO, vtex.pages-graphql indexes merchant page layouts by the major release tag. Bumping to a new major changes that index key. The storefront immediately loses existing block layouts and displays fallback platform defaults.

The agent enforces a verified staging flow instead of direct upgrades in master. You create a production dev workspace, install the theme release, and trigger the updateThemeIds GraphQL mutation. This call rekeys custom routes, redirect maps, and editor configs to the new major version. Omitting updateThemeIds guarantees an empty storefront after cutover.

Promoting via vtex workspace promote triggers a three-way merge against VBase storage. The platform writes automatic snapshots to userData_backup whenever merge collisions arise. That mechanism protects previous edits if unexpected conflicts happen during promotion.

What it helps with

  • prevent merchant layout loss during theme major version upgrades
  • rekey pages and redirect entries across major releases using updateThemeIds
  • validate storefront layouts inside a production dev workspace before promote
  • plan rollback procedures between major versions without rebuilding content

Example prompts for the agent

  • Help me upgrade vendor.store-theme from major 2 to 3 without dropping Site Editor data.
  • Prepare the updateThemeIds mutation payload to migrate pages from major 0 to 1.
  • Audit my deploy workflow before I promote the theme workspace to master.

How to install vtex-io-storefront-theme-versioning

1Skills CLI (Vercel)

npx skills add vtex/skills --skill vtex-io-storefront-theme-versioning -a claude-code

2Manually: put the files in place

~/.claude/skills/vtex-io-storefront-theme-versioning/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/vtex-io-storefront-theme-versioning/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about vtex-io-storefront-theme-versioning

How to install vtex-io-storefront-theme-versioning in Claude Code?

Run npx skills add vtex/skills --skill vtex-io-storefront-theme-versioning -a claude-code. The skill file installs to ~/.claude/skills/vtex-io-storefront-theme-versioning/SKILL.md.

Why does bumping a theme major version erase storefront content?

VTEX IO stores editor entries under keys tagged with the major version number. A newly installed major queries a fresh key space and renders default placeholder blocks instead.

What role does updateThemeIds play during migration?

The mutation transfers Site Editor configurations, custom routes, and URL redirects from the previous major key space to the new one.

Similar skills

Everything for Frontend and UI →
saleor-storefront saleor Provides guidelines and GraphQL patterns for building Saleor storefronts. Helps handle checkout flows, multi-channel setups, and variant selection in AI coding agents. CX Codex +1 2,300installs storefront-builder saleor Walks an agent through building a Saleor storefront: GraphQL wiring, design, then catalog with variant selection. Useful when the frontend exists but the data layer does not. CX Codex +1 384installs shopify-storefront-graphql official Shopify Writes GraphQL queries and mutations against the Shopify Storefront API, searching the docs first and validating the code before it reaches you. CX Codex GP ChatGPT 1installs storefront-best-practices medusajs This skill guides storefront work, from product pages and carts to checkout flows. Use it when building or changing an online store interface. CX Codex +1 4,600installs amazon-storefront-design nexscope-ai A skill that walks you through building an Amazon Store: page layouts, brand story, shoppable images and conversion work. Useful when the storefront needs a plan instead of guesswork. CX Codex +1 1,100installs api-versioning-policy Samuel Berthe Defines an API versioning and deprecation policy covering breaking changes, notice windows, and sunset timelines. Built for teams rolling out /v2 or deprecating endpoints. CX Codex +1 7,600installs

From the same set43

marketplace-rate-limiting Teaches your agent to handle VTEX API 429s: exponential backoff with jitter, rate limit headers, circuit breaker and request queuing. CX Codex +1 1,000installs payment-async-flow Rules for VTEX payment connector code: Boleto, Pix, bank redirects, callbackUrl handling and signature validation. CX Codex +1 1,000installs payment-pci-security Enforces PCI DSS requirements and Secure Proxy routing when building payment connectors that handle card authorization, token exchange, and post-auth requests. CX Codex +1 1,000installs payment-provider-framework This skill guides VTEX IO payment connector work, from PPF wiring to Secure Proxy and build checks. Use it when implementing or maintaining a connector app. CX Codex +1 979installs sales-app-extensibility Guides the creation, styling, and deployment of VTEX Sales App extensions. Works through a seven-stage sequence from project checks to final delivery. CX Codex +1 856installs vtex-io-rootpath A skill for VTEX IO apps in multi-binding stores: shows how to build URLs with the binding's path prefix. Useful when links 404 or point to the wrong locale. CX Codex +1 740installs vtex-io-rbac Walks you through locking down VTEX IO app routes and resources: role policies, resource policies, VRN principals and @auth directives. CX Codex +1 737installs masterdata-storage-strategy Guides data architecture decisions in VTEX, helping configure Master Data JSON schemas with indexing, security, and caching rules before creating entities. CX Codex +1 719installs

Project sponsors

Companies that keep this analytics open
Gold sponsor
Nutra.Club

Impressions, clicks and code copies — open statistics. We keep the numbers public for the same reason NeBlask itself is public. Become a sponsor