// the find
Shopify/hydrogen
Hydrogen lets you build faster headless storefronts in less time, on Shopify.
Hydrogen is Shopify's official React framework for building headless storefronts, built on top of React Router. It's the right tool if you're already committed to Shopify as your commerce backend and want full control over the frontend. If you're not on Shopify, there's nothing here for you.
The two-package split between @shopify/hydrogen (opinionated, React Router-coupled) and @shopify/hydrogen-react (framework-agnostic components and hooks) is well thought out — you can adopt just the primitives without the full stack. The codegen package auto-generates TypeScript types from your Storefront API queries, which catches a real class of bugs at compile time. The calver versioning aligned to Shopify API versions (e.g. 2025.7.x matches API version 2025-07) removes the guesswork about compatibility. The cookbook recipe system with patch files is a practical approach to distributable feature add-ons that doesn't require forking the template.
Calver versioning means breaking changes every three months on a predictable schedule — you're signing up for quarterly upgrade work whether you want it or not. The mini-oxygen local runtime exists specifically because Shopify's Oxygen hosting has a non-standard edge worker environment that differs from standard Node, which means your local dev environment can still diverge from prod in subtle ways. The skeleton template is a starting point but the patch-based cookbook recipes are brittle — they hash-match against specific file contents, so any customization you've made to the patched files means manually resolving conflicts. Hard Shopify lock-in: zero of this transfers if you ever migrate off Shopify.