| name | hydrogen-upgrades |
| description | Step-by-step guides for upgrading Shopify Hydrogen between versions — breaking changes, code diffs, and migration steps for each release. |
Hydrogen 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
For the latest upgrade information from Shopify:
node scripts/search_shopify_docs.mjs "hydrogen upgrade <version>"
node scripts/search_shopify_docs.mjs "hydrogen breaking changes"
node 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 |
Upgrade Process
1. Use the official upgrade tool first
npx @shopify/upgrade
This CLI diffs your project against the latest Hydrogen skeleton and applies changes interactively.
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.ts generated files directly — always regenerate them.
4. Resources
