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/upgradeThis 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 codegenNever edit .d.ts generated files directly — always regenerate them.