Fetch data in Hydrogen
Hydrogen provides a Storefront client to send queries and mutations from Remix loaders and actions to the Storefront API. This guide describes how to install the Storefront client and how to configure its cache options.
Requirements
Anchor link to section titled "Requirements"Make sure you have the following environment variables in place:
PUBLIC_STORE_DOMAIN
PUBLIC_STOREFRONT_API_VERSION
PUBLIC_STOREFRONT_API_TOKEN
PRIVATE_STOREFRONT_API_TOKEN
(Optional)
Step 1: Create and inject the Storefront client
Anchor link to section titled "Step 1: Create and inject the Storefront client"First you need to create and inject the Hydrogen storefront
client into the loader context in Remix. In the server/worker entry file, call createStorefrontClient
and pass its result to getLoadContext
. The following is an example using the Oxygen adapter for Remix:
When deploying to different platforms, you might need to adjust your server entry to other Remix adapters and pass certain parameters in different ways. For example, when running on a stateful Node.js server, the following parameters need to change:
- The
waitUntil
function is not required since the server keeps running after returning a response. - The
cache
instance must follow the Cache API interface. It can store data in-memory or using solutions like Redis. This parameter is optional but recommended. - The
storefrontHeaders.buyerIp
is the client IP address and can be found in therequest
object.
Step 2: Call the Storefront client in Remix loaders and actions
Anchor link to section titled "Step 2: Call the Storefront client in Remix loaders and actions"The storefront
client created in the previous step is now available in the Remix context. You can use this client to send queries and mutations to the Storefront API.
Load data and query the Storefront API
Anchor link to section titled "Load data and query the Storefront API"From a Remix loader, use the storefront.query
function to send GraphQL queries to your Shopify storefront and load data:
Prioritize critical data
Anchor link to section titled "Prioritize critical data"Sometimes, you'll want to prioritize critical data, like product information, while deferring comments or reviews. This speeds up page rendering by showing only important information first. To defer data loading, Remix provides the defer
and Await
utilities. The following is an example:
You can cache data that isn't frequently updated to speed up subsequent queries. Hydrogen supports caching at the sub-request level and keeps data fresh using stale-while-revalidate (SWR). The following is an example:
The default caching option for queries is storefront.CacheShort()
. For more options, refer to caching strategies.
Mutate data
Anchor link to section titled "Mutate data"Data mutation is often performed in Remix actions with the storefront.mutate
function. This is similar to the query
function, except caching is disabled. The following is an example:
Specify a Storefront API version
Anchor link to section titled "Specify a Storefront API version"By default, the Storefront client uses the storefrontApiVersion
parameter that's passed when created as the API version for every request. However, you can override this value in each query or mutation. The following is an example:
- Learn more about API versioning in Shopify.
- Learn more about caching strategies in Hydrogen.
- Test your queries in the local GraphiQL explorer.