About hydrogen-upgrades
hydrogen-upgrades is a skill for Shopify Hydrogen developers, with version-specific migration guides, breaking changes, and code diffs. It also describes using Shopify’s upgrade CLI and includes offline reference guides.
Key features
- 01Version-by-version migration guides
- 02Breaking-change and code-update notes
- 03Step-by-step diffs for version jumps
- 04Offline reference guides
Use cases
- 01Planning a Hydrogen version upgrade
- 02Applying changes across multiple version jumps
- 03Checking required source edits after the upgrade CLI runs
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/hydrogen-upgradesin Claude Code to confirm it loaded.
Bundled files
References and scripts installed along with SKILL.md.
references/upgrade-2024.10.1-to-2025.1.0.mdupgrade-2024.4.7-to-2024.7.1.mdupgrade-2025.1.0-to-2025.1.1.mdupgrade-2025.1.2-to-2025.1.3.mdupgrade-2025.1.3-to-2025.1.4.mdupgrade-2025.5.0-to-2025.7.0.mdupgrade-2025.7.0-to-2026.1.0.mdupgrade-2026.1.0-to-2026.4.7.mdDetails
From the project READMEHydrogen Upgrades
Version-by-version migration guides for upgrading Shopify Hydrogen. Each guide covers breaking changes, required code updates, and step-by-step diffs.
Live Documentation
Run these from this skill's own folder. The helpers ship inside the sibling
shopify-hydrogen skill, so ../shopify-hydrogen/scripts/ exists whenever the
whole pack is installed.
If you installed this skill on its own, that folder is absent and the commands
below fail with MODULE_NOT_FOUND. Add the helpers once:
npx skills add Weaverse/shopify-hydrogen-skills --skill shopify-hydrogen
The references/ files in this skill remain a usable offline fallback if you
would rather not install it.
For the latest upgrade information from Shopify:
node ../shopify-hydrogen/scripts/search_shopify_docs.mjs "hydrogen upgrade <version>"
node ../shopify-hydrogen/scripts/search_shopify_docs.mjs "hydrogen breaking changes"
node ../shopify-hydrogen/scripts/search_shopify_docs.mjs "hydrogen migration"
The curated guides below cover specific version jumps with detailed diffs and Weaverse-specific considerations.
Available Upgrade Guides
| Guide | Key Changes |
|---|---|
| 2024.4.7 → 2024.7.1 | Optimistic variants, new session commit pattern, Layout component refactor, VariantSelector improvements |
| 2024.10.1 → 2025.1.0 | v3_lazyRouteDiscovery flag, stylesheet link tag fixes |
| 2025.1.0 → 2025.1.1 | v3_singleFetch flag, nonce support, json/defer deprecation, B2B stabilization |
| 2025.1.2 → 2025.1.3 | v3_routeConfig flag, Layout export moved to separate file, routes.ts config |
| 2025.1.3 → 2025.1.4 | Session logout fix, VariantSelector deprecation, product query updates, ProductForm refactor |
| 2025.5.0 → 2025.7.0 | Major — React Router 7.9.x migration, context creation, entry point updates |
| 2025.7.0 → 2026.1.0 | Major — @react-router 7.12, @shopify/hydrogen 2026.1.0, Storefront API 2026-01, new cart mutations |
| 2026.1.0 → 2026.4.7 | Major — Storefront API 2026-04, mandatory same-origin Storefront API proxy, Customer Privacy API consent migration, React Router ~7.16 |
Upgrade Process
1. Use the official upgrade tool first
npx shopify hydrogen upgrade
This CLI bumps and installs the required dependencies automatically, then generates a Markdown file listing the required source changes — apply those manually (or feed the file to your agent), then verify. It does not edit your source files itself.
2. Find the right guide above
Match your current version to the appropriate guide. For multi-version jumps, apply each guide in order.
3. Regenerate types after upgrading
npm run codegen
Never edit
.d.tsgenerated files directly — always regenerate them.