Choose a version:

createStorefrontClient

This function extends createStorefrontClient from Hydrogen React. The additional arguments enable internationalization (i18n), caching, and other features particular to React Router and Oxygen.

The returned storefront client includes methods for proxying requests (forward, isStorefrontApiUrl) and collecting tracking information (setCollectedSubrequestHeaders).

Learn more about data fetching in Hydrogen.

Anchor to parametersParameters

HydrogenClientProps<TI18n> & StorefrontClientProps

Anchor to HydrogenClientProps

HydrogenClientProps

Anchor to cache cache Cache: An instance that implements the Cache API
Anchor to i18n i18n TI18n: An object containing a country code and language code
Anchor to logErrors logErrors boolean | ((error?: Error) => boolean): Whether it should print GraphQL errors automatically. Defaults to true
Anchor to storefrontHeaders storefrontHeaders StorefrontHeaders: Storefront API headers. If on Oxygen, use getStorefrontHeaders()
Anchor to storefrontId storefrontId string: The globally unique identifier for the Shop
Anchor to waitUntil waitUntil WaitUntil: The waitUntil function is used to keep the current request/response lifecycle alive even after a response has been sent. It should be provided by your platform.

Anchor to StorefrontClientProps

StorefrontClientProps

Anchor to contentType contentType 'json' | 'graphql': Customizes which "content-type" header is added when using getPrivateTokenHeaders() and getPublicTokenHeaders(). When fetching with a JSON.stringify()-ed body, use "json". When fetching with a body that is a plain string, use "graphql". Defaults to "json"

Can also be customized on a call-by-call basis by passing in 'contentType' to both getPrivateTokenHeaders({...}) and getPublicTokenHeaders({...}), for example: getPublicTokenHeaders({contentType: 'graphql'})
Anchor to privateStorefrontToken privateStorefrontToken string: The Storefront API delegate access token. Refer to the authentication and delegate access token documentation for more details.
Anchor to publicStorefrontToken publicStorefrontToken string: The Storefront API access token. Refer to the authentication documentation for more details.
Anchor to storeDomain storeDomain string: The host name of the domain (eg: {shop}.myshopify.com).
Anchor to storefrontApiVersion storefrontApiVersion string: The Storefront API version. This should almost always be the same as the version Hydrogen React was built for. Learn more about Shopify API versioning for more details.

HydrogenClientProps

cache
An instance that implements the [Cache API](https://developer.mozilla.org/en-US/docs/Web/API/Cache)
```
Cache
```
i18n
An object containing a country code and language code
```
TI18n
```
logErrors
Whether it should print GraphQL errors automatically. Defaults to true
```
boolean | ((error?: Error) => boolean)
```
storefrontHeaders
Storefront API headers. If on Oxygen, use `getStorefrontHeaders()`
```
StorefrontHeaders
```
storefrontId
The globally unique identifier for the Shop
```
string
```
waitUntil
The `waitUntil` function is used to keep the current request/response lifecycle alive even after a response has been sent. It should be provided by your platform.
```
WaitUntil
```

StorefrontClientProps

contentType
Customizes which `"content-type"` header is added when using `getPrivateTokenHeaders()` and `getPublicTokenHeaders()`. When fetching with a `JSON.stringify()`-ed `body`, use `"json"`. When fetching with a `body` that is a plain string, use `"graphql"`. Defaults to `"json"` Can also be customized on a call-by-call basis by passing in `'contentType'` to both `getPrivateTokenHeaders({...})` and `getPublicTokenHeaders({...})`, for example: `getPublicTokenHeaders({contentType: 'graphql'})`
```
'json' | 'graphql'
```
privateStorefrontToken
The Storefront API delegate access token. Refer to the [authentication](https://shopify.dev/api/storefront#authentication) and [delegate access token](https://shopify.dev/apps/auth/oauth/delegate-access-tokens) documentation for more details.
```
string
```
publicStorefrontToken
The Storefront API access token. Refer to the [authentication](https://shopify.dev/api/storefront#authentication) documentation for more details.
```
string
```
storeDomain
The host name of the domain (eg: `{shop}.myshopify.com`).
```
string
```
storefrontApiVersion
The Storefront API version. This should almost always be the same as the version Hydrogen React was built for. Learn more about Shopify [API versioning](https://shopify.dev/api/usage/versioning) for more details.
```
string
```

Anchor to returnsReturns

Anchor to storefront storefront <TI18n>

StorefrontForDoc

cache
The cache instance passed in from the `createStorefrontClient` argument.
```
Cache
```
CacheCustom
Re-export of [`CacheCustom`](/docs/api/hydrogen/utilities/cachecustom).
```
(overrideOptions: AllCacheOptions) => AllCacheOptions
```
CacheLong
Re-export of [`CacheLong`](/docs/api/hydrogen/utilities/cachelong).
```
(overrideOptions?: AllCacheOptions) => AllCacheOptions
```
CacheNone
Re-export of [`CacheNone`](/docs/api/hydrogen/utilities/cachenone).
```
() => NoStoreStrategy
```
CacheShort
Re-export of [`CacheShort`](/docs/api/hydrogen/utilities/cacheshort).
```
(overrideOptions?: AllCacheOptions) => AllCacheOptions
```
generateCacheControlHeader
Re-export of [`generateCacheControlHeader`](/docs/api/hydrogen/utilities/generatecachecontrolheader).
```
(cacheOptions: AllCacheOptions) => string
```
getApiUrl
Creates the fully-qualified URL to your store's GraphQL endpoint. See [`getStorefrontApiUrl` in Hydrogen React](/docs/api/hydrogen-react/2026-04/utilities/createstorefrontclient#:~:text=storeDomain-,getStorefrontApiUrl,-(props%3F%3A) for more details.
```
(props?: Partial<Pick<StorefrontClientProps, "storefrontApiVersion" | "storeDomain">>) => string
```
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. See [`getPrivateTokenHeaders` in Hydrogen React](/docs/api/hydrogen-react/2026-04/utilities/createstorefrontclient#:~:text=storefrontApiVersion-,getPrivateTokenHeaders,-(props%3F%3A) for more details.
```
(props?: Partial<Pick<StorefrontClientProps, "contentType">> & Pick<StorefrontClientProps, "privateStorefrontToken"> & { buyerIp?: string; }) => Record<string, string>
```
getPublicTokenHeaders
Returns an object that contains headers that are needed for each query to Storefront API GraphQL endpoint. See [`getPublicTokenHeaders` in Hydrogen React](/docs/api/hydrogen-react/2026-04/utilities/createstorefrontclient#:~:text=%27graphql%27.-,getPublicTokenHeaders,-(props%3F%3A) for more details.
```
(props?: Partial<Pick<StorefrontClientProps, "contentType">> & Pick<StorefrontClientProps, "publicStorefrontToken">) => Record<string, string>
```
getShopifyDomain
Creates the fully-qualified URL to your myshopify.com domain. See [`getShopifyDomain` in Hydrogen React](/docs/api/hydrogen-react/2026-04/utilities/createstorefrontclient#:~:text=StorefrontClientReturn-,getShopifyDomain,-(props%3F%3A) for more details.
```
(props?: Partial<Pick<StorefrontClientProps, "storeDomain">>) => string
```
i18n
The `i18n` object passed in from the `createStorefrontClient` argument.
```
TI18n
```

mutate

The function to run a mutation on Storefront API.

<TData = any>(mutation: string, options: StorefrontMutationOptionsForDocs) => Promise<TData & StorefrontError>

query

The function to run a query on Storefront API.

<TData = any>(query: string, options: StorefrontQueryOptionsForDocs) => Promise<TData & StorefrontError>

AllCacheOptions

Override options for a cache strategy.

maxAge
The maximum amount of time in seconds that a resource will be considered fresh. See `max-age` in the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#:~:text=Response%20Directives-,max%2Dage,-The%20max%2Dage).
```
number
```
mode
The caching mode, generally `public`, `private`, or `no-store`.
```
string
```
sMaxAge
Similar to `maxAge` but specific to shared caches. See `s-maxage` in the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#s-maxage).
```
number
```
staleIfError
Indicate that the cache should serve the stale response if an error occurs while revalidating the cache. See `stale-if-error` in the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#stale-if-error).
```
number
```
staleWhileRevalidate
Indicate that the cache should serve the stale response in the background while revalidating the cache. See `stale-while-revalidate` in the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#stale-while-revalidate).
```
number
```

NoStoreStrategy

mode
```
string
```

StorefrontMutationOptionsForDocs

displayName
The name of the query for debugging in the Subrequest Profiler.
```
string
```
headers
Additional headers for this query.
```
HeadersInit
```
storefrontApiVersion
Override the Storefront API version for this query.
```
string
```
variables
The variables for the GraphQL mutation statement.
```
Record<string, unknown>
```

StorefrontError

errors
```
StorefrontApiErrors
```

StorefrontApiErrors

JsonGraphQLError[] | undefined

JsonGraphQLError

extensions
Reserved for implementors to extend the protocol however they see fit, and hence there are no additional restrictions on its contents.
```
{ [key: string]: unknown; }
```
locations
If an error can be associated to a particular point in the requested GraphQL document, it should contain a list of locations.
```
{ line: number; column: number; }[]
```
message
```
string
```
name
```
string
```
path
If an error can be associated to a particular field in the GraphQL result, it _must_ contain an entry with the key `path` that details the path of the response field which experienced the error. This allows clients to identify whether a null result is intentional or caused by a runtime error.
```
(string | number)[]
```
stack
```
string
```

StorefrontQueryOptionsForDocs

cache
The cache strategy for this query. Default to max-age=1, stale-while-revalidate=86399.
```
CachingStrategy
```
displayName
The name of the query for debugging in the Subrequest Profiler.
```
string
```
headers
Additional headers for this query.
```
HeadersInit
```
storefrontApiVersion
Override the Storefront API version for this query.
```
string
```
variables
The variables for the GraphQL query statement.
```
Record<string, unknown>
```

CachingStrategy

Use the `CachingStrategy` to define a custom caching mechanism for your data. Or use one of the pre-defined caching strategies: CacheNone, CacheShort, CacheLong.

maxAge
The maximum amount of time in seconds that a resource will be considered fresh. See `max-age` in the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#:~:text=Response%20Directives-,max%2Dage,-The%20max%2Dage).
```
number
```
mode
The caching mode, generally `public`, `private`, or `no-store`.
```
string
```
sMaxAge
Similar to `maxAge` but specific to shared caches. See `s-maxage` in the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#s-maxage).
```
number
```
staleIfError
Indicate that the cache should serve the stale response if an error occurs while revalidating the cache. See `stale-if-error` in the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#stale-if-error).
```
number
```
staleWhileRevalidate
Indicate that the cache should serve the stale response in the background while revalidating the cache. See `stale-while-revalidate` in the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#stale-while-revalidate).
```
number
```

Examples

import {createStorefrontClient} from '@shopify/hydrogen';

import {

createRequestHandler,

getStorefrontHeaders,

} from '@shopify/hydrogen/oxygen';

export default {

async fetch(request, env, executionContext) {

/* Create a Storefront client with your credentials and options */

const {storefront} = createStorefrontClient({

/* Cache API instance */

cache: await caches.open('hydrogen'),

/* Runtime utility in serverless environments */

waitUntil: (p) => executionContext.waitUntil(p),

/* Private Storefront API token for your store */

privateStorefrontToken: env.PRIVATE_STOREFRONT_API_TOKEN,

/* Public Storefront API token for your store */

publicStorefrontToken: env.PUBLIC_STOREFRONT_API_TOKEN,

/* Your store domain: "{shop}.myshopify.com" */

storeDomain: env.PUBLIC_STORE_DOMAIN,

/**

* Storefront API headers containing:

* - buyerIp: The IP address of the customer.

* - requestGroupId: A unique ID to group all the logs for this request.

* - cookie: The 'cookie' header from the request.

storefrontHeaders: getStorefrontHeaders(request),

});

const handleRequest = createRequestHandler({

build: remixBuild,

mode: process.env.NODE_ENV,

/* Inject the Storefront client in the Remix context */

getLoadContext: () => ({storefront}),

});

return handleRequest(request);

};

Examples

Example code

JavaScript

import {createStorefrontClient} from '@shopify/hydrogen';
import {
  createRequestHandler,
  getStorefrontHeaders,
} from '@shopify/hydrogen/oxygen';
export default {
  async fetch(request, env, executionContext) {
    /* Create a Storefront client with your credentials and options */
    const {storefront} = createStorefrontClient({
      /* Cache API instance */
      cache: await caches.open('hydrogen'),
      /* Runtime utility in serverless environments */
      waitUntil: (p) => executionContext.waitUntil(p),
      /* Private Storefront API token for your store */
      privateStorefrontToken: env.PRIVATE_STOREFRONT_API_TOKEN,
      /* Public Storefront API token for your store */
      publicStorefrontToken: env.PUBLIC_STOREFRONT_API_TOKEN,
      /* Your store domain: "{shop}.myshopify.com" */
      storeDomain: env.PUBLIC_STORE_DOMAIN,
      /**
       * Storefront API headers containing:
       * - buyerIp: The IP address of the customer.
       * - requestGroupId: A unique ID to group all the logs for this request.
       * - cookie: The 'cookie' header from the request.
       */
      storefrontHeaders: getStorefrontHeaders(request),
    });

    const handleRequest = createRequestHandler({
      build: remixBuild,
      mode: process.env.NODE_ENV,
      /* Inject the Storefront client in the Remix context */
      getLoadContext: () => ({storefront}),
    });

    return handleRequest(request);
  },
};

TypeScript

import {createStorefrontClient} from '@shopify/hydrogen';
import * as serverBuild from 'virtual:react-router/server-build';
import {
  createRequestHandler,
  getStorefrontHeaders,
} from '@shopify/hydrogen/oxygen';

export default {
  async fetch(
    request: Request,
    env: Record<string, string>,
    executionContext: ExecutionContext,
  ) {
    /* Create a Storefront client with your credentials and options */
    const {storefront} = createStorefrontClient({
      /* Cache API instance */
      cache: await caches.open('hydrogen'),
      /* Runtime utility in serverless environments */
      waitUntil: (p: Promise<unknown>) => executionContext.waitUntil(p),
      /* Private Storefront API token for your store */
      privateStorefrontToken: env.PRIVATE_STOREFRONT_API_TOKEN,
      /* Public Storefront API token for your store */
      publicStorefrontToken: env.PUBLIC_STOREFRONT_API_TOKEN,
      /* Your store domain: "{shop}.myshopify.com" */
      storeDomain: env.PUBLIC_STORE_DOMAIN,
      /**
       * Storefront API headers containing:
       * - buyerIp: The IP address of the customer.
       * - requestGroupId: A unique ID to group all the logs for this request.
       * - cookie: The 'cookie' header from the request.
       */
      storefrontHeaders: getStorefrontHeaders(request),
    });

    const handleRequest = createRequestHandler({
      build: serverBuild,
      mode: process.env.NODE_ENV,
      /* Inject the Storefront client in the Remix context */
      getLoadContext: () => ({storefront}),
    });

    return handleRequest(request);
  },
};

Anchor to RelatedRelated

Was this page helpful?