Skip to main content

Hydrogen overview

tip

Hydrogen 2.0 is out now. These archival Hydrogen 1.0 docs are provided only to assist developers during their upgrade process. Please migrate as soon as possible.

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​

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.

A diagram that shows what Hydrogen includes: Vite offerings and Shopify-specific components, hooks, and utilities

Note: The SSR and hydration middleware is similar to existing Vite SSR implementations. However, Hydrogen uses React Server Components, which affects SSR.

Templates​

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.

The Demo Store template
Demo Store template

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.{% if includes.prop == 'concept' %} Learn more about working with third-party data sources.{% endif %}

A diagram that shows how the Hydrogen components, hooks, and utilities consume data

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​

The following diagram shows the request workflow for Hydrogen apps, based on the platform where Hydrogen is being hosted:

A diagram that illustrates the request workflow for Hydrogen apps, based on the platform where Hydrogen is being hosted

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​

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:

You can configure the default entry points for your app.

Oxygen​

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​

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.

Next steps​