git:20260326.f15bd25 to git:20260409.42c2ef2

12 added, 0 removed. Audit A to A.

---

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:

+ ```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](./references/upgrade-2024.4.7-to-2024.7.1.md) | Optimistic variants, new session commit pattern, Layout component refactor, VariantSelector improvements |

| [2024.10.1 → 2025.1.0](./references/upgrade-2024.10.1-to-2025.1.0.md) | `v3_lazyRouteDiscovery` flag, stylesheet link tag fixes |

| [2025.1.0 → 2025.1.1](./references/upgrade-2025.1.0-to-2025.1.1.md) | `v3_singleFetch` flag, nonce support, `json`/`defer` deprecation, B2B stabilization |

| [2025.1.2 → 2025.1.3](./references/upgrade-2025.1.2-to-2025.1.3.md) | `v3_routeConfig` flag, Layout export moved to separate file, `routes.ts` config |

| [2025.1.3 → 2025.1.4](./references/upgrade-2025.1.3-to-2025.1.4.md) | Session logout fix, `VariantSelector` deprecation, product query updates, `ProductForm` refactor |

| [2025.5.0 → 2025.7.0](./references/upgrade-2025.5.0-to-2025.7.0.md) | **Major** — React Router 7.9.x migration, context creation, entry point updates |

| [2025.7.0 → 2026.1.0](./references/upgrade-2025.7.0-to-2026.1.0.md) | **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.

### 4. Resources

- [Hydrogen changelog](https://github.com/Shopify/hydrogen/blob/main/packages/hydrogen/CHANGELOG.md)

- [Hydrogen skeleton](https://github.com/Shopify/hydrogen/tree/main/templates/skeleton)