{"id":"79c3b15f-b45f-430b-866b-3f0d7cb577ce","shortId":"qRf4Hf","kind":"skill","title":"hydrogen-upgrades","tagline":"Step-by-step guides for upgrading Shopify Hydrogen between versions — breaking changes, code diffs, and migration steps for each release.","description":"# Hydrogen Upgrades\n\nVersion-by-version migration guides for upgrading Shopify Hydrogen. Each guide covers breaking changes, required code updates, and step-by-step diffs.\n\n## Live Documentation\n\nFor the latest upgrade information from Shopify:\n\n```bash\nnode scripts/search_shopify_docs.mjs \"hydrogen upgrade <version>\"\nnode scripts/search_shopify_docs.mjs \"hydrogen breaking changes\"\nnode scripts/search_shopify_docs.mjs \"hydrogen migration\"\n```\n\nThe curated guides below cover specific version jumps with detailed diffs and Weaverse-specific considerations.\n\n## Available Upgrade Guides\n\n| Guide | Key Changes |\n|-------|-------------|\n| [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 |\n| [2024.10.1 → 2025.1.0](./references/upgrade-2024.10.1-to-2025.1.0.md) | `v3_lazyRouteDiscovery` flag, stylesheet link tag fixes |\n| [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 |\n| [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 |\n| [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 |\n| [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 |\n| [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 |\n\n## Upgrade Process\n\n### 1. Use the official upgrade tool first\n\n```bash\nnpx @shopify/upgrade\n```\n\nThis CLI diffs your project against the latest Hydrogen skeleton and applies changes interactively.\n\n### 2. Find the right guide above\n\nMatch your current version to the appropriate guide. For multi-version jumps, apply each guide in order.\n\n### 3. Regenerate types after upgrading\n\n```bash\nnpm run codegen\n```\n\n> Never edit `.d.ts` generated files directly — always regenerate them.\n\n### 4. Resources\n\n- [Hydrogen changelog](https://github.com/Shopify/hydrogen/blob/main/packages/hydrogen/CHANGELOG.md)\n- [Hydrogen skeleton](https://github.com/Shopify/hydrogen/tree/main/templates/skeleton)","tags":["hydrogen","upgrades","shopify","skills","weaverse","agent-skills","agentic-commerce","shopify-hydrogen","shopify-hydrogen-skills","weaverse-hydrogen"],"capabilities":["skill","source-weaverse","skill-hydrogen-upgrades","topic-agent-skills","topic-agentic-commerce","topic-shopify-hydrogen","topic-shopify-hydrogen-skills","topic-weaverse-hydrogen"],"categories":["shopify-hydrogen-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/Weaverse/shopify-hydrogen-skills/hydrogen-upgrades","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add Weaverse/shopify-hydrogen-skills","source_repo":"https://github.com/Weaverse/shopify-hydrogen-skills","install_from":"skills.sh"}},"qualityScore":"0.466","qualityRationale":"deterministic score 0.47 from registry signals: · indexed on github topic:agent-skills · 33 github stars · SKILL.md body (2,457 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-01T12:57:20.836Z","embedding":null,"createdAt":"2026-04-18T22:21:46.480Z","updatedAt":"2026-05-01T12:57:20.836Z","lastSeenAt":"2026-05-01T12:57:20.836Z","tsv":"'-01':187 '/references/upgrade-2024.10.1-to-2025.1.0.md':112 '/references/upgrade-2024.4.7-to-2024.7.1.md':98 '/references/upgrade-2025.1.0-to-2025.1.1.md':122 '/references/upgrade-2025.1.2-to-2025.1.3.md':135 '/references/upgrade-2025.1.3-to-2025.1.4.md':149 '/references/upgrade-2025.5.0-to-2025.7.0.md':162 '/references/upgrade-2025.7.0-to-2026.1.0.md':176 '/shopify/hydrogen/blob/main/packages/hydrogen/changelog.md)':265 '/shopify/hydrogen/tree/main/templates/skeleton)':270 '1':193 '2':217 '2024.10.1':110 '2024.4.7':96 '2024.7.1':97 '2025.1.0':111,120 '2025.1.1':121 '2025.1.2':133 '2025.1.3':134,147 '2025.1.4':148 '2025.5.0':160 '2025.7.0':161,174 '2026':186 '2026.1.0':175,183 '3':241 '4':259 '7.12':181 '7.9':166 'alway':256 'api':185 'appli':214,236 'appropri':229 'avail':90 'b2b':131 'bash':60,200,246 'break':15,40,68 'cart':189 'chang':16,41,69,95,215 'changelog':262 'cli':204 'code':17,43 'codegen':249 'commit':103 'compon':106 'config':146 'consider':89 'context':169 'cover':39,78 'creation':170 'curat':75 'current':225 'd.ts':252 'defer':129 'deprec':130,154 'detail':83 'diff':18,50,84,205 'direct':255 'document':52 'edit':251 'entri':171 'export':140 'file':144,254 'find':218 'first':199 'fix':119,152 'flag':115,125,138 'generat':253 'github.com':264,269 'github.com/shopify/hydrogen/blob/main/packages/hydrogen/changelog.md)':263 'github.com/shopify/hydrogen/tree/main/templates/skeleton)':268 'guid':8,32,38,76,92,93,221,230,238 'hydrogen':2,12,25,36,63,67,72,211,261,266 'hydrogen-upgrad':1 'improv':109 'inform':57 'interact':216 'json':128 'jump':81,235 'key':94 'latest':55,210 'layout':105,139 'lazyroutediscoveri':114 'link':117 'live':51 'logout':151 'major':163,177 'match':223 'migrat':20,31,73,168 'move':141 'multi':233 'multi-vers':232 'mutat':190 'never':250 'new':101,188 'node':61,65,70 'nonc':126 'npm':247 'npx':201 'offici':196 'optimist':99 'order':240 'pattern':104 'point':172 'process':192 'product':155 'productform':158 'project':207 'queri':156 'react':164,179 'react-rout':178 'refactor':107,159 'regener':242,257 'releas':24 'requir':42 'resourc':260 'right':220 'routeconfig':137 'router':165,180 'routes.ts':145 'run':248 'scripts/search_shopify_docs.mjs':62,66,71 'separ':143 'session':102,150 'shopifi':11,35,59 'shopify/hydrogen':182 'shopify/upgrade':202 'singlefetch':124 'skeleton':212,267 'skill' 'skill-hydrogen-upgrades' 'source-weaverse' 'specif':79,88 'stabil':132 'step':5,7,21,47,49 'step-by-step':4,46 'storefront':184 'stylesheet':116 'support':127 'tag':118 'tool':198 'topic-agent-skills' 'topic-agentic-commerce' 'topic-shopify-hydrogen' 'topic-shopify-hydrogen-skills' 'topic-weaverse-hydrogen' 'type':243 'updat':44,157,173 'upgrad':3,10,26,34,56,64,91,191,197,245 'use':194 'v3':113,123,136 'variant':100 'variantselector':108,153 'version':14,28,30,80,226,234 'version-by-vers':27 'weavers':87 'weaverse-specif':86 'x':167","prices":[{"id":"62a03e36-8aa1-4f2b-96ab-1eb77be5a32e","listingId":"79c3b15f-b45f-430b-866b-3f0d7cb577ce","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"Weaverse","category":"shopify-hydrogen-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T22:21:46.480Z"}],"sources":[{"listingId":"79c3b15f-b45f-430b-866b-3f0d7cb577ce","source":"github","sourceId":"Weaverse/shopify-hydrogen-skills/hydrogen-upgrades","sourceUrl":"https://github.com/Weaverse/shopify-hydrogen-skills/tree/main/skills/hydrogen-upgrades","isPrimary":false,"firstSeenAt":"2026-04-18T22:21:46.480Z","lastSeenAt":"2026-05-01T12:57:20.836Z"}],"details":{"listingId":"79c3b15f-b45f-430b-866b-3f0d7cb577ce","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"Weaverse","slug":"hydrogen-upgrades","github":{"repo":"Weaverse/shopify-hydrogen-skills","stars":33,"topics":["agent-skills","agentic-commerce","shopify-hydrogen","shopify-hydrogen-skills","weaverse-hydrogen"],"license":null,"html_url":"https://github.com/Weaverse/shopify-hydrogen-skills","pushed_at":"2026-04-24T10:12:43Z","description":"Dedicated agent skills for building, upgrading, and maintaining Shopify Hydrogen storefronts — works with Claude, Cursor, Copilot, and more.","skill_md_sha":"16ee4a58ffcc8055c2efb494e37c7e9593b799b2","skill_md_path":"skills/hydrogen-upgrades/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/Weaverse/shopify-hydrogen-skills/tree/main/skills/hydrogen-upgrades"},"layout":"multi","source":"github","category":"shopify-hydrogen-skills","frontmatter":{"name":"hydrogen-upgrades","description":"Step-by-step guides for upgrading Shopify Hydrogen between versions — breaking changes, code diffs, and migration steps for each release."},"skills_sh_url":"https://skills.sh/Weaverse/shopify-hydrogen-skills/hydrogen-upgrades"},"updatedAt":"2026-05-01T12:57:20.836Z"}}