# vtex-io-storefront-theme-versioning

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

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 777 installs · ★ 46
- Author: vtex
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/vtex/skills/tree/HEAD/skills/vtex-io-storefront-theme-versioning/SKILL.md
- Updated: 2026-10-14
- HTML: https://affpapa.org/en/nevibecode/skills/vtex-io-storefront-theme-versioning

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill vtex-io-storefront-theme-versioning -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.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/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill vtex-io-storefront-theme-versioning -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/vtex-io-storefront-theme-versioning/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill vtex-io-storefront-theme-versioning -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/vtex-io-storefront-theme-versioning/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install vtex/skills vtex-io-storefront-theme-versioning
```

2. **Manually: put the files in place**
- File: `.github/skills/vtex-io-storefront-theme-versioning/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill vtex-io-storefront-theme-versioning -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/vtex/skills --path skills/vtex-io-storefront-theme-versioning
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/vtex-io-storefront-theme-versioning/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add vtex/skills --skill vtex-io-storefront-theme-versioning -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/vtex/skills/tree/HEAD/skills/vtex-io-storefront-theme-versioning/SKILL.md

## When to use it
- 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
- 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.

## Similar
- [saleor-storefront](https://affpapa.org/en/nevibecode/skills/saleor-storefront.md) — skill · 2300 installs
- [storefront-builder](https://affpapa.org/en/nevibecode/skills/storefront-builder.md) — skill · 384 installs
- [shopify-storefront-graphql](https://affpapa.org/en/nevibecode/skills/shopify-storefront-graphql.md) — skill · 1 install
- [storefront-best-practices](https://affpapa.org/en/nevibecode/skills/storefront-best-practices.md) — skill · 4600 installs
- [amazon-storefront-design](https://affpapa.org/en/nevibecode/skills/amazon-storefront-design.md) — skill · 1100 installs
- [api-versioning-policy](https://affpapa.org/en/nevibecode/skills/api-versioning-policy.md) — skill · 7600 installs

From the same set: [vtex/skills](https://affpapa.org/en/nevibecode/by/vtex/skills.md) — 43 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md