How We Built Hydrogen: A React Framework for Building Custom Storefronts

Summary

Hydrogen is a React framework for building custom Shopify storefronts, created to help merchants use the Storefront API without giving up capabilities associated with Liquid storefronts. Shopify built it around React Server Components and React 18’s streaming server-side rendering, using component-level data fetching, a preload cache to parallelize nested queries, and experimental loggers for query waterfalls and unused GraphQL properties. The framework evolved through more than 1,200 pull requests and 3,000 commits, with rigid components removed after feedback and nearly all exported GraphQL fragments eliminated to make queries more discoverable. The post reports that some demo store routes cut load time in half and that Hydrogen is used in production at Allbirds, Shopify Supply, Shopify Hardware, and Shopify, while future plans include a new router and incremental adoption from Liquid storefronts.

Context

Merchants, especially larger merchants, needed a way to build custom storefronts with Shopify’s Storefront API without losing capabilities provided by Liquid storefronts. They also faced decisions and implementation work involving frameworks, cart and product-selection primitives, performance, testing, accessibility, hosting, scaling, observability, and analytics. The post says JAMStack-oriented frameworks were not considered a good fit for Shopify’s inherently dynamic commerce sites.

Approach / What changed

Shopify built Hydrogen as a dynamic React framework using React Server Components and React 18 streaming server-side rendering. It introduced component-level data fetching, a preload cache for parallelizing nested queries, loggers for request waterfalls and unused GraphQL properties, and a reduced set of framework primitives. The team iterated through feedback, open-source contributions, production use, and collaboration with React, Vite, hosting platforms, and other ecosystem projects.

Takeaways

• Hydrogen’s preload cache hoists nested data queries so they can execute in parallel instead of creating network request waterfalls.
• Removing almost every exported GraphQL fragment made requested data more discoverable and encouraged developers to fine-tune queries; some demo store routes saw load times cut in half.
• The team removed rigid Product and SelectedVariant.AddToCartButton components because fixed GraphQL payloads prevented custom queries and third-party data integration.

Related reading