skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
weaverse/shopify-hydrogen-skills155 installs

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-upgrades
view source ↗

Is 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

GuideKey Changes
2024.4.7 → 2024.7.1Optimistic variants, new session commit pattern, Layout component refactor, VariantSelector improvements
2024.10.1 → 2025.1.0v3_lazyRouteDiscovery flag, stylesheet link tag fixes
2025.1.0 → 2025.1.1v3_singleFetch flag, nonce support, json/defer deprecation, B2B stabilization
2025.1.2 → 2025.1.3v3_routeConfig flag, Layout export moved to separate file, routes.ts config
2025.1.3 → 2025.1.4Session logout fix, VariantSelector deprecation, product query updates, ProductForm refactor
2025.5.0 → 2025.7.0Major — React Router 7.9.x migration, context creation, entry point updates
2025.7.0 → 2026.1.0Major — @react-router 7.12, @shopify/hydrogen 2026.1.0, Storefront API 2026-01, new cart mutations
2026.1.0 → 2026.4.7Major — Storefront API 2026-04, mandatory same-origin Storefront API proxy, Customer Privacy API consent migration, React Router ~7.16
2026.4.7 → 2026.10.2Rewrite — 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/hydrogen to ~2026.4.x and stay on @weaverse/hydrogen 5.x: a ^2026.4.0 range 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.ts files directly.
  • 2026.10: there is no codegen. Result types come from gql() documents through @shopify/hydrogen/ts-plugin, and npm run typecheck runs react-router typegen && tsc --noEmit && hydrogen gql check --fail-on-warn.

4. Resources

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>