Hydrogen React
Bring the best parts of Hydrogen to more React frameworks, like Next.js and Gatsby, and accelerate headless development using Shopify’s pre-built React components including Cart, Shop Pay, and Shopify Analytics.
Hydrogen React provides a set of performant React components, reusable functions, and utilities for interacting with the Storefront API. By handling business logic, data processing, and state management, Hydrogen React reduces complexity and boilerplate so that you can focus on building your custom storefront's unique brand experience.
When to use Hydrogen React
Anchor link to section titled "When to use Hydrogen React"Use Hydrogen React to build a custom storefront in any third-party, React-based framework, such as Next.js or Gatsby.
The following diagram illustrates an example custom storefront stack that uses Hydrogen React:
For examples of other custom storefront stacks, refer to Build options.
Get started with Hydrogen React
Anchor link to section titled "Get started with Hydrogen React"Get started with Hydrogen React by installing the package, importing the feature that you want to use in your app, enabling Storefront API access by installing the Headless channel, and authenticating your Storefront API client.
Requirements
Anchor link to section titled "Requirements"- You have the staff role on the Shopify store that you're working with.
- You have Apps and channels permissions on the Shopify store that you're working with.
Step 1: Install the @shopify/hydrogen-react package
Anchor link to section titled "Step 1: Install the @shopify/hydrogen-react package"Run one of the following commands to install the package:
Import the component, hook, or utility that you want to use in your Hydrogen app. Refer to the Hydrogen React reference for a full list of components, hooks, and utilities available.
Step 2: Enable Storefront API access
Anchor link to section titled "Step 2: Enable Storefront API access"Enable Storefront API access by installing the Headless channel with the following procedure, or you can install it from the Shopify App Store. Installing the Headless channel provides you with public and private access tokens.
From your Shopify admin, under Sales channels, click Headless.
Click Create storefront.
Step 3: Manage permissions
Anchor link to section titled "Step 3: Manage permissions"Managing permissions controls what your custom storefront can display from your Shopify store.
From your Shopify admin, select the Headless sales channel.
From the list, select the storefront.
Beside Storefront API permissions, click Edit.
Select the permissions for the storefront.
Click Save.
Step 4: Update the Storefront client
Anchor link to section titled "Step 4: Update the Storefront client"To make it easier to query the Storefront API, Hydrogen React includes a Storefront client that exposes a helper function called createStorefrontClient(). The client can take in public and private access tokens for making unauthenticated and authenticated requests to the Storefront API, respectively.
Import
createStorefrontClient()and add the private access token to the helper function.The following is an example:
Use the private token in your server-side queries.
When using the private token to make requests from your server to the Storefront API, you should also pass in the customer's IP address to the
getPrivateTokenHeaders()function. This enables the Storefront API to perform load balancing and other security features for you.When the API request isn't on behalf of a buyer, such as during a static site build, the header isn't needed.
The following is an example using NextJS's
getServerSideProps:The specific framework and runtime that you're using determines how you can retrieve the customer's IP address.
- Consult the Hydrogen React README for information on development and production bundles, Hydrogen React in the browser, and improving your development experience by enabling GraphQL autocompletion and setting TypeScript types.
- Refer to the Hydrogen React reference to see the full list of components, hooks, and utilities available.