---
title: Hydrogen
description: Hydrogen is Shopify’s opinionated stack for headless commerce, built on [React Router](https://reactrouter.com/home). It provides a set of tools, utilities, and best-in-class examples for building dynamic and performant commerce applications.
api_version: 2025-07
api_name: hydrogen
source_url:
  html: https://shopify.dev/docs/api/hydrogen
  md: https://shopify.dev/docs/api/hydrogen.md
---

# Hydrogen

Hydrogen is Shopify’s opinionated stack for headless commerce, built on [React Router](https://reactrouter.com/home). It provides a set of tools, utilities, and best-in-class examples for building dynamic and performant commerce applications.

***

## Setup

1. Create a new Hydrogen project with your preferred package manager.
2. Import components, hooks, or utilities that you want to use in your app. For more, see the [getting started guide](https://shopify.dev/docs/custom-storefronts/hydrogen/getting-started).

[Tutorial - Getting started with Hydrogen and Oxygen](https://shopify.dev/docs/custom-storefronts/hydrogen/getting-started)

### Examples

* #### Create a new Hydrogen project

  ##### npm

  ```undefined
  npm create @shopify/hydrogen@latest
  ```

  ##### yarn

  ```undefined
  yarn create @shopify/hydrogen
  ```

## Authentication

To make full use of Hydrogen, you need to authenticate with and make requests to the [Storefront API](https://shopify.dev/docs/api/storefront) and the [Customer Account API](https://shopify.dev/docs/api/customer). Hydrogen includes full-featured API clients to securely handle API queries and mutations.

You can create access tokens for your own Shopify store by [installing the Hydrogen sales channel](https://apps.shopify.com/hydrogen), which includes built-in support for Oxygen, Shopify’s global edge hosting platform. Or install the [Headless sales channel](https://apps.shopify.com/headless) to host your Hydrogen app anywhere.

Both the Storefront API and Customer Account API offer public credentials for client-side applications.

[Install - Hydrogen sales channel](https://apps.shopify.com/hydrogen)

[Install - Headless sales channel](https://apps.shopify.com/headless)

### Examples

* #### Authenticate a Hydrogen app

  ##### server.js

  ```javascript
  /**
   * server.js
   * ---------
   * Create a storefront client.
   * Check the server.js file in the root of your new Hydrogen project to see
   * an example implementation of this function. If you start from an official
   * Hydrogen template (Hello World or Demo Store), then the client is already
   * set up for you. Update the Shopify store domain and API token to start
   * querying your own store inventory.
   */
  const {storefront} = createStorefrontClient({
    cache,
    waitUntil,
    i18n: {language: 'EN', country: 'US'},
    // `env` provides access to runtime data, including environment variables
    publicStorefrontToken: env.PUBLIC_STOREFRONT_API_TOKEN,
    privateStorefrontToken: env.PRIVATE_STOREFRONT_API_TOKEN,
    storeDomain: env.PUBLIC_STORE_DOMAIN,
    storefrontId: env.PUBLIC_STOREFRONT_ID,
    storefrontHeaders: getStorefrontHeaders(request),
  });
  ```

  ##### .env

  ```undefined
  # These API credentials fetch example inventory from the Hydrogen Demo Store
  # https://hydrogen.shop
  #
  # Replace with your own store domain and Storefront API token

  SESSION_SECRET="foobar"
  PUBLIC_STOREFRONT_API_TOKEN="3b580e70970c4528da70c98e097c2fa0"
  PUBLIC_STORE_DOMAIN="hydrogen-preview.myshopify.com"
  ```

## Versioning

Hydrogen is tied to specific versions of the [Storefront API](https://shopify.dev/api/storefront), which is versioned quarterly. For example, if you're using Storefront API version `2023-10`, then Hydrogen versions `2023.10.x` are fully compatible.

Caution

If a Storefront API version includes breaking changes, then the corresponding Hydrogen version will include the same breaking changes.

[Learn more - Shopify API versioning](https://shopify.dev/docs/api/usage/versioning)

[Learn more - API release notes](https://shopify.dev/docs/api/release-notes)

## How Hydrogen works with Hydrogen React

Hydrogen is [built on React Router](https://shopify.dev/docs/custom-storefronts/hydrogen/project-structure). But many of the components, hooks and utilities built into Hydrogen come from [Hydrogen React](https://shopify.dev/docs/api/hydrogen-react), an underlying package that’s framework-agnostic. For convenience, the Hydrogen package re-exports those resources. This means that if you’re building a Hydrogen app, then you should import modules from the `@shopify/hydrogen` package.

### Examples

* #### Importing Hydrogen components

  ##### example-page.jsx

  ```jsx
  import {ShopPayButton} from '@shopify/hydrogen';

  export function renderShopPayButton({variantId, storeDomain}) {
    return <ShopPayButton variantIds={[variantId]} storeDomain={storeDomain} />;
  }
  ```

## Resources

[Custom storefronts on Shopify\
\
Learn more about how to design, build, and manage custom storefronts on Shopify.](https://shopify.dev/custom-storefronts)

[Hydrogen on GitHub\
\
Follow the Hydrogen project, file bugs and feature requests, preview upcoming features, and more](https://github.com/Shopify/hydrogen)