hydrogen-upgrades

Original：🇺🇸 English

Translated

Step-by-step guides for upgrading Shopify Hydrogen between versions — breaking changes, code diffs, and migration steps for each release.

2installs

Sourceweaverse/shopify-hydrogen-skills

Added on2026-04-09

NPX Install

npx skill4agent add weaverse/shopify-hydrogen-skills hydrogen-upgrades

SKILL.md Content

View Translation Comparison →

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:

bash

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

bash

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

bash

npm run codegen

Never edit
.d.ts
generated files directly — always regenerate them.

hydrogen-upgrades

NPX Install

Tags

SKILL.md Content

Hydrogen Upgrades

Live Documentation

Available Upgrade Guides

Upgrade Process

1. Use the official upgrade tool first

2. Find the right guide above

3. Regenerate types after upgrading

4. Resources