---
title: Hydrogen
description: >-
  Hydrogen is Shopify’s opinionated stack for headless commerce, built on
  [Remix](https://remix.run). It provides a set of tools, utilities, and
  best-in-class examples for building dynamic and performant commerce
  applications.
api_version: 2023-04
api_name: hydrogen
source_url:
  html: 'https://shopify.dev/docs/api/hydrogen/2023-04'
  md: 'https://shopify.dev/docs/api/hydrogen/2023-04.md'
---

# Hydrogen

Hydrogen is Shopify’s opinionated stack for headless commerce, built on [Remix](https://remix.run). 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 detailed instructions, see the Getting Started Guide.

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

### 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). Hydrogen includes a full-featured [API client](https://shopify.dev/docs/api/hydrogen/current/utilities/createstorefrontclient) to securely handle API queries and mutations.

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

Apps have access to [two kinds of tokens](https://shopify.dev/docs/api/usage/authentication#access-tokens-for-the-storefront-api): a public API token, which can be used in client-side code, and a private API token, which should only be used in server-side contexts and never exposed publicly.

[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: `https://${env.PUBLIC_STORE_DOMAIN}`,
    storefrontApiVersion: env.PUBLIC_STOREFRONT_API_VERSION || '2023-04',
    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_STOREFRONT_API_VERSION="2023-04"
  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-04`, then Hydrogen versions `2023.4.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 - Developer changelog](https://shopify.dev/changelog)

## How Hydrogen works with Hydrogen React

Hydrogen is [built on Remix](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)