Hydrogen overview
Hydrogen is a front-end web development framework used for building Shopify custom storefronts. It includes the structure, components, and tooling you need to get started so you can spend your time styling and designing features that make your brand unique.
How Hydrogen works
Anchor link to section titled "How Hydrogen works"Hydrogen is the approach you use to build a custom storefront. It contains a framework and a library of components, hooks, and utilities:
Hydrogen framework: Hydrogen provides a Vite plugin which offers server-side rendering (SSR), hydration middleware, and client component code transformations.
Hydrogen components, hooks, and utilities: Hydrogen includes components, hooks, and utilities that support features and concepts that exist in Shopify. They're accessible, performant, and ready for use. They also help to reduce the initial complexity and boilerplate needed for building a custom storefront.
Hydrogen provides the following templates to help you get started building Shopify custom storefronts:
- Hello World: A minimal template for developers who want to build their Hydrogen storefront from the very beginning.
- Demo Store: The default template installed when creating a new Hydrogen storefront. It’s a full-featured Hydrogen storefront that uses live production data provided by Shopify. The demo store is an opinionated, production-ready Hydrogen storefront with the full purchase journey out-of-the-box.
For more information, refer to Hydrogen templates.
Data sources
Anchor link to section titled "Data sources"Hydrogen is built and optimized to use data coming from Shopify's Storefront API. The shape of the data passed to components, hooks, and utilities corresponds and conforms to the structure based on the GraphQL types from the Storefront API.
Hydrogen can also support data from third-party sources. If you want to use Hydrogen components with a third-party data source, then data from the third-party source must first be transformed into the types expected by the Hydrogen components, hooks, and utilities, and then passed on to the components, hooks, and utilities.
Performance optimizations
Anchor link to section titled "Performance optimizations"Hydrogen's architecture enables a mix of static and dynamic data fetching between client- and server-side for optimized performance. It's built on top of newer web technology, and takes a modern approach to web development to offer the following:
Built-in caching controls to handle dynamic content and minimize API calls for speed and performance.
Server-side rendering to optimize the initial load.
React Server Components, an opinionated data-fetching and rendering flow for React apps. React Server Components offer an improved development experience. Components render fast, which allows you to see your work instantly as you’re building it.
Request workflow for Hydrogen apps
Anchor link to section titled "Request workflow for Hydrogen apps"The following diagram shows the request workflow for Hydrogen apps, based on the platform where Hydrogen is being hosted:
Node.js runtime
Anchor link to section titled "Node.js runtime"The Hydrogen app is hosted on a Node.js platform like Heroku, Vercel, or Netlify. If you've generated a Node.js server, then you can run it inside a Docker container like GCP, AWS, Azure, or Fly.io.
By default, Hydrogen includes a @shopify/hydrogen/platforms/node package, which is a Connect-based Node.js server. Alternatively, you can use your own server.
Worker (v8) runtime
Anchor link to section titled "Worker (v8) runtime"The Hydrogen app is hosted on a worker platform like Oxygen, Netlify, Vercel, or Cloudflare.
By default, Hydrogen includes a @shopify/hydrogen/platforms/worker package for server-side rendering. The Cache API and KV API are powered by Oxygen, Cloudflare, or another runtime adapter.
Hydrogen includes the following default entry points for your app:
- Client entry point:
@shopify/hydrogen/entry-client, which is included inindex.htmland used for hydration purposes - Server entry point:
App.server.jsx
You can configure the default entry points for your app.
Oxygen is Shopify's recommended deployment platform for Hydrogen storefronts. Oxygen removes the need to maintain server infrastructure, and enables you to manage and deploy Hydrogen storefronts. You can deploy different Hydrogen storefronts to Oxygen environments, enabling you to preview and share different versions of storefronts.
Limitations
Anchor link to section titled "Limitations"Hydrogen can only be used to build Shopify web storefronts. Currently, Hydrogen doesn't support building other types of custom storefronts, including mobile apps, video games, and smart devices.
- Get started with Hydrogen and begin building a custom storefront.
- Learn about React Server Components, an opinionated data-fetching and rendering workflow for React apps.
- Learn how to deploy your Hydrogen storefront to Oxygen and other runtimes.