Skip to main content

Storefront API client

The createStorefrontClient function creates a typed Storefront API client for browser code, server-side rendering, or background jobs such as webhooks. Use the client to run queries and mutations with the customer's cookies and locale, and to cache query results.

Import createStorefrontClient and its option and client types from @shopify/hydrogen.

Pass the client a request context from createShopifyRequestContext.


Creates a Storefront API client that runs typed queries and mutations against your store.

Set type based on where your code runs and whether customer context is available:

publicprivateprivate_no_buyer_context
Runs inBrowser or mobileServer-side renderingBackground server code
TokenPublic access token, or nonePrivate access tokenPrivate access token
Customer contextBrowser request contextYou forward trusted buyerIpNone
Best forClient-side fetchesSSR with customer contextWebhooks, background jobs

Pass a request context from createShopifyRequestContext. The client forwards the incoming request's cookies and Sec-GPC header to the Storefront API, and fills $country and $language variables from the context's locale. The client reads the request headers once, when you create the client. Create a client for each incoming request, and create a client at module scope only with a static request context.

Keep private clients in server code, where the token can't reach browsers. The function throws an error when you create either private client type in a browser. The function throws a TypeError when the request context of a private client has no buyerIp.

required

The client type, request context, and store configuration for the new client.

The client, with a graphql() method that runs queries and mutations.

The config options depend on the client type. A public client takes PublicClientOptions, a private client takes PrivateClientOptions, and a private_no_buyer_context client takes PrivateNoBuyerContextClientOptions.

Options for a public client, which runs in the browser or a mobile app. Pass a public access token, or omit the token for tokenless access.

Tokenless access can't read some Storefront API fields, including product tags, metaobjects, metafields, menus, and customers.

Anchor to storeDomain
storeDomain
string
required

Your store's domain, such as my-store.myshopify.com. Hydrogen adds https:// when the domain has no protocol, and removes trailing slashes. createStorefrontClient throws an error for an empty domain.

Anchor to apiVersion
apiVersion
string

The Storefront API version that the client queries. Defaults to the version that Hydrogen bundles. To send some queries to another version, such as unstable, create a second client with that version. Type inference always uses Hydrogen's bundled schema. Write your own types for fields outside the bundled schema.

Anchor to cache
cache

The cache that stores query results. The client caches only queries that pass a cache strategy. The client never caches mutations or results with GraphQL errors.

Anchor to defaultTimeoutInMs
defaultTimeoutInMs
number

How long a request can run before the client throws a StorefrontTimeoutError, in milliseconds. Defaults to 30000. Set 0 to turn off the timeout. Stale-while-revalidate refreshes use the same timeout, or 30,000 when the timeout is 0. createStorefrontClient throws an error for a negative value.

Anchor to fetch
fetch
Fetch

The fetch function that the client calls. Defaults to globalThis.fetch. createStorefrontClient throws an error when neither exists.

Anchor to publicStorefrontToken
publicStorefrontToken
string | undefined

Your public Storefront API access token. Omit the token for tokenless access. createStorefrontClient throws an error for an empty string.

Anchor to storefrontId
storefrontId
string

Your Hydrogen storefront's ID. The client sends the ID in the Shopify-Storefront-Id header of every request.

Anchor to waitUntil
waitUntil

Keeps the runtime alive while the client writes to the cache in the background, such as a worker's waitUntil function. Without the function, each cached query waits for its cache write before it resolves.

Anchor to privateclientoptionsPrivateClientOptions

Options for a private client, which runs during server-side rendering and forwards the customer's IP address to the Storefront API. Set buyerIp on the request context before you create the client.

Anchor to privateStorefrontToken
privateStorefrontToken
string
required

Your private Storefront API access token. Keep the token out of browser code. createStorefrontClient throws an error when the token is missing.

Anchor to storeDomain
storeDomain
string
required

Your store's domain, such as my-store.myshopify.com. Hydrogen adds https:// when the domain has no protocol, and removes trailing slashes. createStorefrontClient throws an error for an empty domain.

Anchor to apiVersion
apiVersion
string

The Storefront API version that the client queries. Defaults to the version that Hydrogen bundles. To send some queries to another version, such as unstable, create a second client with that version. Type inference always uses Hydrogen's bundled schema. Write your own types for fields outside the bundled schema.

Anchor to cache
cache

The cache that stores query results. The client caches only queries that pass a cache strategy. The client never caches mutations or results with GraphQL errors.

Anchor to defaultTimeoutInMs
defaultTimeoutInMs
number

How long a request can run before the client throws a StorefrontTimeoutError, in milliseconds. Defaults to 30000. Set 0 to turn off the timeout. Stale-while-revalidate refreshes use the same timeout, or 30,000 when the timeout is 0. createStorefrontClient throws an error for a negative value.

Anchor to fetch
fetch
Fetch

The fetch function that the client calls. Defaults to globalThis.fetch. createStorefrontClient throws an error when neither exists.

Anchor to storefrontId
storefrontId
string

Your Hydrogen storefront's ID. The client sends the ID in the Shopify-Storefront-Id header of every request.

Anchor to waitUntil
waitUntil

Keeps the runtime alive while the client writes to the cache in the background, such as a worker's waitUntil function. Without the function, each cached query waits for its cache write before it resolves.

Anchor to privatenobuyercontextclientoptionsPrivateNoBuyerContextClientOptions

Options for a private client without buyer context, for background jobs, webhooks, and other server code with no customer. The client sends a private access token and no customer IP address.

Anchor to privateStorefrontToken
privateStorefrontToken
string
required

Your private Storefront API access token. Keep the token out of browser code. createStorefrontClient throws an error when the token is missing.

Anchor to storeDomain
storeDomain
string
required

Your store's domain, such as my-store.myshopify.com. Hydrogen adds https:// when the domain has no protocol, and removes trailing slashes. createStorefrontClient throws an error for an empty domain.

Anchor to apiVersion
apiVersion
string

The Storefront API version that the client queries. Defaults to the version that Hydrogen bundles. To send some queries to another version, such as unstable, create a second client with that version. Type inference always uses Hydrogen's bundled schema. Write your own types for fields outside the bundled schema.

Anchor to cache
cache

The cache that stores query results. The client caches only queries that pass a cache strategy. The client never caches mutations or results with GraphQL errors.

Anchor to defaultTimeoutInMs
defaultTimeoutInMs
number

How long a request can run before the client throws a StorefrontTimeoutError, in milliseconds. Defaults to 30000. Set 0 to turn off the timeout. Stale-while-revalidate refreshes use the same timeout, or 30,000 when the timeout is 0. createStorefrontClient throws an error for a negative value.

Anchor to fetch
fetch
Fetch

The fetch function that the client calls. Defaults to globalThis.fetch. createStorefrontClient throws an error when neither exists.

Anchor to storefrontId
storefrontId
string

Your Hydrogen storefront's ID. The client sends the ID in the Shopify-Storefront-Id header of every request.

Anchor to waitUntil
waitUntil

Keeps the runtime alive while the client writes to the cache in the background, such as a worker's waitUntil function. Without the function, each cached query waits for its cache write before it resolves.

Examples

TypeScript

import { createShopifyRequestContext, createStorefrontClient } from "@shopify/hydrogen";

const requestContext = createShopifyRequestContext({
request: { headers: new Headers() },
i18n: { country: "US", language: "EN" },
});

export const storefront = createStorefrontClient({
type: "public",
requestContext,
config: {
storeDomain: process.env.PUBLIC_STORE_DOMAIN!,
publicStorefrontToken: process.env.PUBLIC_STOREFRONT_API_TOKEN,
},
});

Chooses the kind of Storefront API client to create. Use public in the browser, with a public access token or none. Use private during server-side rendering, with a private token and the customer's IP address. Use private_no_buyer_context in background jobs and webhooks, with a private token and no customer.

"public" | "private" | "private_no_buyer_context"

Anchor to publicstorefrontclientPublicStorefrontClient

The type of a client that you create with type: "public".

Anchor to apiUrl
apiUrl
string
required

The Storefront API GraphQL endpoint that the client calls.

Anchor to graphql
graphql
<const Doc extends | string>(doc: Doc, ...options: <<Doc>, Extra>) => Promise<<<Doc>>>
required

Runs a Storefront API query or mutation and returns a typed result. Pass a gql document or a plain query string. When the operation declares $country or $language, the client sets the variable from the request context and overrides any value you pass.

The method throws an error when a query passes a cache strategy and the client has no cache, or when the strategy uses private mode. A catch block for StorefrontApiError doesn't catch this configuration error. To cache customer-specific data, use createRunWithCache with a key unique to the customer.

RequestContext["i18n"]
required

The country and language that the client sends for $country and $language variables.

Anchor to requestContext
requestContext
RequestContext
required

The request context that you passed to createStorefrontClient.

Anchor to storeUrl
storeUrl
string
required

Your store's URL with its protocol, such as https://my-store.myshopify.com.

Type
required

The client type that you passed to createStorefrontClient.

Anchor to storefrontId
storefrontId
string

The storefront ID from the client options.

Anchor to privatestorefrontclientPrivateStorefrontClient

The type of a client that you create with type: "private". The client's request context includes buyerIp.

Anchor to apiUrl
apiUrl
string
required

The Storefront API GraphQL endpoint that the client calls.

Anchor to graphql
graphql
<const Doc extends | string>(doc: Doc, ...options: <<Doc>, Extra>) => Promise<<<Doc>>>
required

Runs a Storefront API query or mutation and returns a typed result. Pass a gql document or a plain query string. When the operation declares $country or $language, the client sets the variable from the request context and overrides any value you pass.

The method throws an error when a query passes a cache strategy and the client has no cache, or when the strategy uses private mode. A catch block for StorefrontApiError doesn't catch this configuration error. To cache customer-specific data, use createRunWithCache with a key unique to the customer.

RequestContext["i18n"]
required

The country and language that the client sends for $country and $language variables.

Anchor to requestContext
requestContext
RequestContext
required

The request context that you passed to createStorefrontClient.

Anchor to storeUrl
storeUrl
string
required

Your store's URL with its protocol, such as https://my-store.myshopify.com.

Type
required

The client type that you passed to createStorefrontClient.

Anchor to storefrontId
storefrontId
string

The storefront ID from the client options.

Anchor to requestscopedprivatestorefrontclientRequestScopedPrivateStorefrontClient

The type of a private client with the default request context. Use the type to annotate a private client without naming your request context type.

Anchor to apiUrl
apiUrl
string
required

The Storefront API GraphQL endpoint that the client calls.

Anchor to graphql
graphql
<const Doc extends | string>(doc: Doc, ...options: <<Doc>, Extra>) => Promise<<<Doc>>>
required

Runs a Storefront API query or mutation and returns a typed result. Pass a gql document or a plain query string. When the operation declares $country or $language, the client sets the variable from the request context and overrides any value you pass.

The method throws an error when a query passes a cache strategy and the client has no cache, or when the strategy uses private mode. A catch block for StorefrontApiError doesn't catch this configuration error. To cache customer-specific data, use createRunWithCache with a key unique to the customer.

Omit<, "pathPrefix"> & { pathPrefix: string; }
required

The country and language that the client sends for $country and $language variables.

Anchor to requestContext
requestContext
RequestContext
required

The request context that you passed to createStorefrontClient.

Anchor to storeUrl
storeUrl
string
required

Your store's URL with its protocol, such as https://my-store.myshopify.com.

Type
required

The client type that you passed to createStorefrontClient.

Anchor to storefrontId
storefrontId
string

The storefront ID from the client options.

Anchor to privatenobuyercontextstorefrontclientPrivateNoBuyerContextStorefrontClient

The type of a client that you create with type: "private_no_buyer_context", for background jobs and webhooks.

Anchor to apiUrl
apiUrl
string
required

The Storefront API GraphQL endpoint that the client calls.

Anchor to graphql
graphql
<const Doc extends | string>(doc: Doc, ...options: <<Doc>, Extra>) => Promise<<<Doc>>>
required

Runs a Storefront API query or mutation and returns a typed result. Pass a gql document or a plain query string. When the operation declares $country or $language, the client sets the variable from the request context and overrides any value you pass.

The method throws an error when a query passes a cache strategy and the client has no cache, or when the strategy uses private mode. A catch block for StorefrontApiError doesn't catch this configuration error. To cache customer-specific data, use createRunWithCache with a key unique to the customer.

RequestContext["i18n"]
required

The country and language that the client sends for $country and $language variables.

Anchor to requestContext
requestContext
RequestContext
required

The request context that you passed to createStorefrontClient.

Anchor to storeUrl
storeUrl
string
required

Your store's URL with its protocol, such as https://my-store.myshopify.com.

Type
required

The client type that you passed to createStorefrontClient.

Anchor to storefrontId
storefrontId
string

The storefront ID from the client options.


To cache queries, pass a cache in the client config and a Cache strategy in each query's options.


Was this page helpful?