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.

hydrogen-upgrades