Hydrogen components, hooks, and utilities overview
Hydrogen contains a set of Shopify-specific commerce components, hooks, and utilities that help accelerate your development process. This guide provides a complete reference of the components, hooks, and utilities that Hydrogen offers, and their relationships to each other.
How Hydrogen and Hydrogen React work together
Anchor link to section titled "How Hydrogen and Hydrogen React work together"Many of the components, hooks and utilities built into Hydrogen come from 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 them from the @shopify/hydrogen package. You can view the complete list of these framework-agnostic resources below.
The resources outlined on this page are unique to Hydrogen. Some are built to be compatible only with Remix, while others are intended to work only on Oxygen. In these cases, these resources can only be imported from the @shopify/hydrogen package.
@shopify/hydrogen resources:
Anchor link to section titled "@shopify/hydrogen resources:"| Import | Type | Description |
|---|---|---|
| Seo | Component | Render SEO data in the document head. |
| createStorefrontClient | Utility | Create a client to manage queries to the Storefront API. |
| generateCacheControlHeader | Utility | Process a caching strategy into a request header. |
| graphiqlLoader | Utility | Load the GraphiQL query browser in your development environment. |
| storefrontRedirect | Utility | Redirect visitors based on online store URL route settings. |
| CacheNone | Cache strategy | Instruct clients not to cache data. |
| CacheShort | Cache strategy | Instruct clients to cache data for a short period of time. |
| CacheLong | Cache strategy | Instruct clients to cache data for a long period of time. |
| CacheCustom | Cache strategy | Declare a custom cache strategy. |
The <Seo /> component renders SEO meta tags in the document head. SEO metadata is set on a per-route basis using Remix loader functions. Learn more about how SEO works in Hydrogen.
createStorefrontClient
Anchor link to section titled "createStorefrontClient"This function extends createStorefrontClient from Hydrogen React. The additional arguments enable internationalization (i18n), caching, and other features particular to Remix and Oxygen.
Learn more about data fetching in Hydrogen.
createStorefrontClient arguments
Anchor link to section titled "createStorefrontClient arguments"| Parameter | Type | Required? | Description |
|---|---|---|---|
| cache | Cache | No | A Cache API instance. |
| i18n | I18nBase | No | An object containing a country code and a language code. |
| privateStorefrontToken | String | No | A valid Storefront API private access token. |
| publicStorefrontToken | String | Yes | A valid Storefront API public access token. |
| storeDomain | String | Yes | The host name of the domain (Example: https://{shop}.myshopify.com). |
| storefrontHeaders | StorefrontHeaders | No | Storefront API headers |
| storefrontId | String | No | The globally unique identifier for the Shop |
| storefrontApiVersion | String | No | The Storefront API version. This should almost always be the same as the version Hydrogen was built for. Learn more about Shopify API versioning for more details. |
| waitUntil | ExecutionContext | No | A runtime utility for serverless environments. |
| buyerIp | String | No | (Deprecated) The IP address of the client. |
| requestGroupId | String | No | (Deprecated) A unique ID that correlates all sub-requests together. Defaults to a UUID. |
createStorefrontClient returns
Anchor link to section titled "createStorefrontClient returns"A storefront object of the following:
| Fields | Description |
|---|---|
query |
The function to run a query on storefront api. |
mutate |
The function to run a mutation on storefront api. |
cache? |
The cache instance passed in from the createStorefrontClient argument. |
CacheNone |
Re-export of CacheNone. |
CacheLong |
Re-export of CacheLong. |
CacheShort |
Re-export of CacheShort. |
CacheCustom |
Re-export of CacheCustom. |
getShopifyDomain |
Returns the fully qualified URL to your shop domain. |
getStorefrontApiUrl |
Returns the fully qualified URL to your store's GraphQL endpoint. |
getPrivateTokenHeaders |
Returns an object that contains headers that are needed for each query to Storefront API GraphQL endpoint for API calls made from a server. |
getPublicTokenHeaders |
Returns an object that contains headers that are needed for each query to Storefront API GraphQL endpoint. See createStorefrontClient return object for more details. |
isApiError |
Determines if the error is resulted from a Storefront API call. |
i18n |
The i18n object passed in from the createStorefrontClient argument. Defaults to I18nBase. |
graphiqlLoader
Anchor link to section titled "graphiqlLoader"This function creates an instance of GraphiQL in your Hydrogen app when running on a development server. This enables you to explore, write, and test GraphQL queries using your store's live data from the Storefront API. You can visit the GraphiQL app at your storefront route /graphiql. This function accepts Remix LoaderArgs if you need to customize GraphiQL's behavior. Learn more about using GraphiQL in Hydrogen.
graphiqlLoader arguments
Anchor link to section titled "graphiqlLoader arguments"| Parameter | Type | Required? | Description |
|---|---|---|---|
| args | LoaderArgs | Yes | Remix loader data. |
storefrontRedirect
Anchor link to section titled "storefrontRedirect"Queries the Storefront API to see if there is any redirect created for the current route and performs it. Otherwise, it returns the response passed in the parameters. Useful for conditionally redirecting after a 404 response.
storefrontRedirect arguments
Anchor link to section titled "storefrontRedirect arguments"| Parameter | Type | Required? | Description |
|---|---|---|---|
storefront |
Storefront | Yes | The storefront instance created by createStorefrontClient. |
request |
Request | Yes | The request object from your server. |
response |
Response | No | The response object that your app has generated. Default value is new Response('Not Found', {status: 404}. |
Cache strategies
Anchor link to section titled "Cache strategies"Hydrogen provides a selection of built-in caching strategies. Use these to fine-tune cache performance when hosting your Hydrogen app on Oxygen. Note that the exact time duration of preset cache strategies might change. If you need exact control over cache duration, use CacheCustom.
The CacheNone() strategy instructs caches not to store any data.
The function accepts no arguments.
The CacheShort strategy instructs caches to store data for 1 second, and staleWhileRevalidate data for an additional 9 seconds. Note: these time values are subject to change.
CacheShort arguments
Anchor link to section titled "CacheShort arguments"| Parameter | Type | Required? | Description |
|---|---|---|---|
overrideOptions |
CachingStrategy | No | An object overriding the default strategy values. See CachingStrategy for the available options. |
The CacheLong strategy instructs caches to store data for 1 hour, and staleWhileRevalidate data for an additional 23 hours. Note: these time values are subject to change.
CacheLong arguments
Anchor link to section titled "CacheLong arguments"| Parameter | Type | Required? | Description |
|---|---|---|---|
overrideOptions |
CachingStrategy | No | An object overriding the default strategy values. See CachingStrategy for the available options. |
CacheCustom
Anchor link to section titled "CacheCustom"This allows you to create your own caching strategy, using any of the options available in a CachingStrategy object.
CacheCustom arguments
Anchor link to section titled "CacheCustom arguments"| Parameter | Type | Required? | Description |
|---|---|---|---|
overrideOptions |
CachingStrategy | Yes | An object overriding the default strategy values. See CachingStrategy for the available options. |
generateCacheControlHeader
Anchor link to section titled "generateCacheControlHeader"This utility function accepts a CachingStrategy object and returns a string with the corresponding cache-control headers.
generateCacheControlHeader arguments
Anchor link to section titled "generateCacheControlHeader arguments"| Parameter | Type | Required? | Description |
|---|---|---|---|
overrideOptions |
CachingStrategy | Yes | An object overriding the default strategy values. See CachingStrategy for the available options. Returns a string containing the resulting cache-control headers. |
CachingStrategy options
Anchor link to section titled "CachingStrategy options"You can optionally customize Hydrogen and Oxygen's built-in caching strategies by passing in a CachingStrategy object to override individual options. These options are compatible with the HTTP Cache-Control API.
| Parameter | Type | Required? | Description |
|---|---|---|---|
| mode | String | No | How clients should cache data. Accepts values of PUBLIC or PRIVATE. |
| maxAge | Number | No | How long to cache data, in seconds. |
| staleWhileRevalidate | Number | No | How long to serve stale data while refreshing in the background, in seconds. |
| sMaxAge | Number | No | How long a response is considered fresh for, in seconds. Applies only to shared (or PUBLIC) caches. |
| staleIfError | Number | No | How long to serve a stale response, in seconds. Applies in cases where an upstream server produces an error. |
Additional components, hooks, and utilities
Anchor link to section titled "Additional components, hooks, and utilities"You can import the following Hydrogen React resources into your Hydrogen app from @shopify/hydrogen.
| Components | |
| Hooks | |
| Utilities | |
| Constants |