hydrogen-upgrades

$npx mdskill add Weaverse/shopify-hydrogen-skills/hydrogen-upgrades

Guides Shopify Hydrogen upgrades with breaking changes and code diffs.

  • Solves migration pain between Hydrogen versions with step-by-step guides.
  • Depends on Shopify docs and curated upgrade references for each version.
  • Recommends specific upgrade path based on current and target versions.
  • Delivers detailed diffs, migration steps, and Weaverse-specific considerations.

SKILL.md

.github/skills/hydrogen-upgradesView on GitHub ↗
---
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)

More from Weaverse/shopify-hydrogen-skills

SkillDescription
cloning-websites-to-weaverseUse when recreating a reference website or brand hub in this Hydrogen plus Weaverse repo, especially when deciding whether to reuse sections, add global styles, update theme schema, or resolve conflicts between the live site and project brand guidelines.
figma-to-weaverseUse when recreating a Figma design as Hydrogen + Weaverse pages in this repo — turning a Figma file, frame, or flow into reusable Weaverse sections. Triggers on a figma.com URL, "build this design", "implement this Figma", or "create the storefront from the design". The Figma counterpart of cloning-websites-to-weaverse.
generating-weaverse-project-jsonUse when generating Weaverse project export JSON for import into the Weaverse editor. Triggers on requests to create, build, or produce a Weaverse project JSON file from a site migration, design spec, page layout description, or existing export. Also use when converting section plans into importable project and pages data.
hydrogen-analytics-trackingEnd-to-end analytics & conversion tracking on Shopify Hydrogen — GTM, GA4 (browser + Measurement Protocol), Meta Pixel + CAPI, Google Ads, consent mode, CSP, Oxygen full-page cache. Real-world patterns from production deployments.
hydrogen-cookbooksStep-by-step implementation guides for building features in a Shopify Hydrogen storefront — bundles, combined listings, customer accounts, 3D models, performance, variant media, and Weaverse integration.
setup-weaverse-projectSet up, create, scaffold, or clone a new Weaverse Hydrogen storefront locally from a Weaverse theme. Use CLI-first setup, boot a live demo-store preview before asking for Shopify credentials, then make it the merchant's own with env, GitHub, and Builder preview connection.
shopify-hydrogenCore Shopify Hydrogen APIs — createHydrogenContext, cart handler, CartForm, caching strategies, pagination, SEO, variant selection, analytics, and CSP.
theme-updateSafely update a Weaverse Pilot theme to the latest version — detects current version, fetches release diffs, plans changes category-by-category, preserves customizations, verifies build.
weaverse-content-apiUse when reading or updating live Weaverse content programmatically — pulling projects/pages/theme settings, bulk-editing page content, pushing AI-generated copy, deleting pages, or uploading media to Shopify for use in Weaverse. Triggers on requests to update a Weaverse project via API, push content to a live project, run bulk content edits, or upload images/assets to Shopify from automation.
weaverse-hydrogenBuild Shopify Hydrogen storefronts with Weaverse — components, schemas, loaders, theming, data fetching, React Router v7, deployment, and advanced features.