Why a Commerce Framework Needs to Be Dynamic
Hydrogen is Shopify’s React framework for custom storefronts, and it’s been in development for over a year. The core problem it solves: how can merchants use the Storefront API to build a fully custom storefront without losing the conveniences of a Liquid-based theme—things like cart primitives, product selection, performance tooling, accessibility, hosting, and observability?
Before Hydrogen, merchants had to choose between bulky templates or starting from zero. Shopify concluded that commerce is inherently dynamic, and that JAMStack-style frameworks—which pre-build static pages and require constant rebuilds—weren't the right fit. Hydrogen was built as a dynamic storefront framework powered by React, designed to handle these concerns by default.
Iterating From an Empty Repo
On April 1, 2021, the Hydrogen project began as an empty GitHub repository. Since then, it has grown through more than 1,200 pull requests and 3,000 commits. Development was a process of trial and error: components were added, tested by early adopters, and sometimes removed after feedback revealed they weren't useful.
One clear example was the original set of components, which included Product and SelectedVariant.AddToCartButton. These were designed as helpers that wrapped product pages and used React context for child components to interact with each other. Developers quickly found them too rigid: the components expected a specific GraphQL payload, preventing merchants from modifying queries or including data from third-party sources. Since that flexibility is a given for custom storefronts, many components were more neat than useful. Many were removed, leaving a leaner framework focused on genuinely useful primitives.
Data Fetching Without Waterfalls
Early on, Hydrogen adopted server components and React 18's streaming SSR, which meant it needed a data fetching strategy for the server. Rather than inventing another top-level loader API like loader() or getStaticProps(), Hydrogen was built with component-level data fetching.
The drawback to naive component-level fetching is the network request waterfall: nested components block rendering while waiting on parent data. To fix that, Hydrogen includes a preload cache that hoists nested queries so they execute in parallel. When enabled, preloaded queries start running as soon as the page is requested instead of falling into a waterfall pattern. An experimental query timing logger can also detect when a waterfall is happening, signaling that a query should be preloaded. This area remains experimental, and Shopify expects the broader React ecosystem to eventually move toward similar patterns.
GraphQL fragments went through a similar revision. Early in the developer preview, Hydrogen exported fragment strings from UI components to make it easy to plug in required data. As components gained more features, fragments became bloated—they pulled in required variables, large default pagination values, and many metafield and variant nodes. Developers ended up fetching more data than needed, and the hidden fragment contents inside the npm package made it hard to see what was actually being requested.
The solution was twofold. First, a new experimental logger was added to detect unused properties in GraphQL queries, alerting developers to remove fields that aren't being used in their components. Second, nearly every fragment export was removed from the npm package. Newly scaffolded apps have more verbose queries, but the data is transparent, and developers can fine-tune queries instead of relying on opaque fragments. The result was significant: some routes in the demo store template had their load time cut in half.
Building in Public Pays Off
Being an open-source project brought more than feedback. External contributions have added options to useShopQuery, fixed errors in the demo store template, and added internationalization support. Since November 2021, more than a dozen external developers have had contributions accepted.
Public discussion also shaped the framework's direction. Proposed routing strategies, caching API designs, and developer requests went through public discourse. Feedback from the community led to TypeScript adoption in demo store templates.
The Bets: React Server Components and Vite
Hydrogen's roadmap was built on a few risky technology choices taken in early 2021.
Betting on React Server Components
In December 2020, React introduced server components (RSC): components rendered on the server with zero client-side JavaScript required. Shopify saw this as an ideal fit, even though RSC wasn't yet released. Instead of waiting, they built a naive version that worked in Vite, reverse-engineering the RSC payload that serializes components for browser interactivity. This let the team continue building a framework with component-level data fetching rather than stalling.
Later, Hydrogen switched to an official version of server components powered by React's payload. Shopify describes RSC as its biggest technical bet for Hydrogen today, citing the mix-and-match modularity between first-party and third-party components, which isn't available in other frameworks. In non-RSC frameworks, data fetching is tied to the routing layer, so a server-side data-fetching component can't just be dropped into an app. Shopify is working with React's core team at Meta and Next.js at Vercel on the server components design, contributing feedback on server module conventions. The goal is an API that works across frameworks and stays aligned with the evolving RSC specification.
Betting on Vite
The other major bet was on Vite, chosen while webpack was still the default for most front-end projects. Vite's SSR support was still in beta, but Shopify found it fast, extensible, and popular with developers. The team works directly with the Vite core team on bug fixes and improvements, and Shopify sponsors both Vite and Vue.js as financial backer.
Styling Choices and the Tailwind Question
Tailwind CSS was used in the initial Hydrogen demo to build an interactive product detail page with 3D models, taking advantage of atomic CSS classes to modify component appearances without constantly switching between React components and stylesheets. The choice was informed by Tailwind's strong popularity — the State of CSS 2021 survey placed its developer satisfaction at 78 percent.
Atomic CSS remains a debated approach for styling web applications, and the team recognized not every developer would want Tailwind in their Hydrogen projects. Even so, it proved effective and performant for building and scaling large Hydrogen storefronts in practice.
How Feedback Shaped the Framework
Hydrogen was not built in isolation, and the open-source nature of the project meant interaction with many other open-source projects and deployment across different surfaces. That reality shaped how the team gathered and applied feedback.
Working with Internal Teams
Internal collaboration was essential, particularly with Shopify's API team, which iterates on the Storefront API based on community feedback. That collaboration resulted in a new Cart API, an overhauled schema, and a new private API token designed to improve rate limiting on server-to-server calls.
The Oxygen team worked closely with Hydrogen on the deployment pipeline, defining requirements for the Oxygen runtime such as access to geolocation properties via incoming requests. Other core Shopify teams contributed features to the framework itself, including customer authentication, search engine optimization, and analytics, along with example code showing how to integrate those features.
Dogfooding was a major part of development. Teams at Shopify used Hydrogen in production for products like Linkpop and Shopify Supply, which exposed API limitations and led to concrete improvements.
Collaborating Beyond Shopify
The strongest collaborations happened outside the company. The team met regularly with the React core team to discuss server components, contributing pull requests for new features, bug reports, and bug fixes. A Vite version of the server components plugin is being iterated on upstream.
Work with Vercel focused on defining server components conventions in alignment with Next.js and determining how Hydrogen apps could be deployed on Vercel. The Vite core team also received contributions that added features and fixed bugs. Early on, Cloudflare partnered with Shopify on Oxygen, helping refine the ReadableStream implementation. Hydrogen joined WinterCG and proposed topics like standardized access to cookie headers and runtime variables.
Google's Aurora initiative led to work on a standardized Image component to enforce best practices within Hydrogen from the start. Early adopters like Sanity helped shape early API patterns and created reference implementations such as the Hydrogen Sanity demo store. The Remix team explored a Hydrogen Stack and a way to implement Hydrogen components inside Remix apps. Hosting platforms such as Netlify also worked to make Hydrogen deployment available outside of Oxygen.
What's Next for Hydrogen
Hydrogen has moved beyond the demo stage. It is now in production at Allbirds, Shopify Supply, Shopify Hardware, and Shopify itself, with the npm package downloaded more than 70,000 times per month.
Upcoming work includes deeper integration with the broader Shopify ecosystem, a redesign of server components, a new Hydrogen router, and incremental adoption paths for existing Liquid storefronts.
