hydrogen-upgrades
Step-by-step guides for upgrading Shopify Hydrogen between versions — breaking changes, code diffs, and migration steps for each release.
How do I install this agent skill?
npx skills add https://github.com/weaverse/shopify-hydrogen-skills --skill hydrogen-upgradesIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The hydrogen-upgrades skill provides a comprehensive collection of version-by-version migration guides for Shopify Hydrogen projects. It utilizes official Shopify tools and the author's own CLI for maintenance and upgrades. No security concerns or malicious patterns were identified.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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
Run these from this skill's own folder. The helpers ship inside the sibling
shopify-hydrogen skill, so ../shopify-hydrogen/scripts/ exists whenever the
whole pack is installed.
If you installed this skill on its own, that folder is absent and the commands
below fail with MODULE_NOT_FOUND. Add the helpers once:
npx skills add Weaverse/shopify-hydrogen-skills --skill shopify-hydrogen
The references/ files in this skill remain a usable offline fallback if you
would rather not install it.
For the latest upgrade information from Shopify:
node ../shopify-hydrogen/scripts/search_shopify_docs.mjs "hydrogen upgrade <version>"
node ../shopify-hydrogen/scripts/search_shopify_docs.mjs "hydrogen breaking changes"
node ../shopify-hydrogen/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 |
| 2026.1.0 → 2026.4.7 | Major — Storefront API 2026-04, mandatory same-origin Storefront API proxy, Customer Privacy API consent migration, React Router ~7.16 |
| 2026.4.7 → 2026.10.2 | Rewrite — Hydrogen becomes a request-handler library (server.ts composes the lifecycle, no createHydrogenContext), storefront.graphql(gql()) with explicit cache, cart store at /api/cart, product form store, Customer Account handlers, ShopifyScripts analytics, @weaverse/hydrogen 6 (@weaverse/hydrogen/react-router) |
Upgrade Process
1. Use the official upgrade tool first (classic releases)
npx shopify hydrogen upgrade
For upgrades up to 2026.4.7, this CLI bumps and installs the required dependencies, then generates a Markdown file listing the required source changes — apply those manually (or feed the file to your agent), then verify. It does not edit your source files itself.
The move to 2026.10 is not a version bump: Hydrogen becomes a library and the app owns its request lifecycle. Follow the 2026.4.7 → 2026.10.2 guide and Shopify's packaged migration skill at node_modules/@shopify/hydrogen/skills/migrate-to-hydrogen-2026-10/SKILL.md (install @shopify/hydrogen@2026.10 first). Weaverse themes also run the @weaverse/hydrogen 6 codemod:
npx @weaverse/cli@latest migrate v6 --dry-run # list the files it would change
npx @weaverse/cli@latest migrate v6
Classic projects that are not migrating yet should pin
@shopify/hydrogento~2026.4.xand stay on@weaverse/hydrogen5.x: a^2026.4.0range resolves to 2026.10.
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 or check types after upgrading
- Classic (2026.4 and earlier): regenerate the GraphQL types with
npm run codegen. Never edit the generated.d.tsfiles directly. - 2026.10: there is no codegen. Result types come from
gql()documents through@shopify/hydrogen/ts-plugin, andnpm run typecheckrunsreact-router typegen && tsc --noEmit && hydrogen gql check --fail-on-warn.
4. Resources
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/weaverse/shopify-hydrogen-skills/hydrogen-upgrades">View hydrogen-upgrades on skillZs</a>