--- title: createStorefrontClient description: |- This function extends `createStorefrontClient` from [Hydrogen React](/docs/api/hydrogen-react/2025-04/utilities/createstorefrontclient). The additional arguments enable internationalization (i18n), caching, and other features particular to Remix and Oxygen. Learn more about [data fetching in Hydrogen](/docs/custom-storefronts/hydrogen/data-fetching/fetch-data). api_version: 2025-05 api_name: hydrogen source_url: html: https://shopify.dev/docs/api/hydrogen/latest/utilities/createstorefrontclient md: https://shopify.dev/docs/api/hydrogen/latest/utilities/createstorefrontclient.md --- # create​Storefront​Clientutility This function extends `createStorefrontClient` from [Hydrogen React](https://shopify.dev/docs/api/hydrogen-react/2025-04/utilities/createstorefrontclient). The additional arguments enable internationalization (i18n), caching, and other features particular to Remix and Oxygen. Learn more about [data fetching in Hydrogen](https://shopify.dev/docs/custom-storefronts/hydrogen/data-fetching/fetch-data). ## Parameters `HydrogenClientProps & StorefrontClientProps` ### HydrogenClientProps * cache Cache An instance that implements the [Cache API](https://developer.mozilla.org/en-US/docs/Web/API/Cache) * i18n TI18n An object containing a country code and language code * logErrors boolean | ((error?: Error) => boolean) Whether it should print GraphQL errors automatically. Defaults to true * storefrontHeaders StorefrontHeaders Storefront API headers. If on Oxygen, use `getStorefrontHeaders()` * storefrontId string The globally unique identifier for the Shop * 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. ### HydrogenClientProps * cache An instance that implements the \[Cache API]\(https\://developer.mozilla.org/en-US/docs/Web/API/Cache) ```ts Cache ``` * i18n An object containing a country code and language code ```ts TI18n ``` * logErrors Whether it should print GraphQL errors automatically. Defaults to true ```ts boolean | ((error?: Error) => boolean) ``` * storefrontHeaders Storefront API headers. If on Oxygen, use \`getStorefrontHeaders()\` ```ts StorefrontHeaders ``` * storefrontId The globally unique identifier for the Shop ```ts 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. ```ts WaitUntil ``` ```ts { /** Storefront API headers. If on Oxygen, use `getStorefrontHeaders()` */ storefrontHeaders?: StorefrontHeaders; /** An instance that implements the [Cache API](https://developer.mozilla.org/en-US/docs/Web/API/Cache) */ cache?: Cache; /** The globally unique identifier for the Shop */ storefrontId?: string; /** 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?: WaitUntil; /** An object containing a country code and language code */ i18n?: TI18n; /** Whether it should print GraphQL errors automatically. Defaults to true */ logErrors?: boolean | ((error?: Error) => boolean); } ``` ## Returns * storefront StorefrontForDoc\ ### StorefrontForDoc * cache The cache instance passed in from the \`createStorefrontClient\` argument. ```ts Cache ``` * CacheCustom Re-export of \[\`CacheCustom\`]\(/docs/api/hydrogen/utilities/cachecustom). ```ts (overrideOptions: AllCacheOptions) => AllCacheOptions ``` * CacheLong Re-export of \[\`CacheLong\`]\(/docs/api/hydrogen/utilities/cachelong). ```ts (overrideOptions?: AllCacheOptions) => AllCacheOptions ``` * CacheNone Re-export of \[\`CacheNone\`]\(/docs/api/hydrogen/utilities/cachenone). ```ts () => NoStoreStrategy ``` * CacheShort Re-export of \[\`CacheShort\`]\(/docs/api/hydrogen/utilities/cacheshort). ```ts (overrideOptions?: AllCacheOptions) => AllCacheOptions ``` * generateCacheControlHeader Re-export of \[\`generateCacheControlHeader\`]\(/docs/api/hydrogen/utilities/generatecachecontrolheader). ```ts (cacheOptions: AllCacheOptions) => string ``` * getApiUrl Creates the fully-qualified URL to your store's GraphQL endpoint. See \[\`getStorefrontApiUrl\` in Hydrogen React]\(/docs/api/hydrogen-react/2025-04/utilities/createstorefrontclient#:\~:text=storeDomain-,getStorefrontApiUrl,-(props%3F%3A) for more details. ```ts (props?: Partial>) => 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/2025-04/utilities/createstorefrontclient#:\~:text=storefrontApiVersion-,getPrivateTokenHeaders,-(props%3F%3A) for more details. ```ts (props?: Partial> & Pick & { buyerIp?: string; }) => Record ``` * 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/2025-04/utilities/createstorefrontclient#:\~:text=%27graphql%27.-,getPublicTokenHeaders,-(props%3F%3A) for more details. ```ts (props?: Partial> & Pick) => Record ``` * getShopifyDomain Creates the fully-qualified URL to your myshopify.com domain. See \[\`getShopifyDomain\` in Hydrogen React]\(/docs/api/hydrogen-react/2025-04/utilities/createstorefrontclient#:\~:text=StorefrontClientReturn-,getShopifyDomain,-(props%3F%3A) for more details. ```ts (props?: Partial>) => string ``` * i18n The \`i18n\` object passed in from the \`createStorefrontClient\` argument. ```ts TI18n ``` * mutate The function to run a mutation on Storefront API. ```ts (mutation: string, options: StorefrontMutationOptionsForDocs) => Promise ``` * query The function to run a query on Storefront API. ```ts (query: string, options: StorefrontQueryOptionsForDocs) => Promise ``` ```ts { /** The function to run a query on Storefront API. */ query?: ( query: string, options: StorefrontQueryOptionsForDocs, ) => Promise; /** The function to run a mutation on Storefront API. */ mutate?: ( mutation: string, options: StorefrontMutationOptionsForDocs, ) => Promise; /** The cache instance passed in from the `createStorefrontClient` argument. */ cache?: Cache; /** Re-export of [`CacheNone`](/docs/api/hydrogen/utilities/cachenone). */ CacheNone?: typeof CacheNone; /** Re-export of [`CacheLong`](/docs/api/hydrogen/utilities/cachelong). */ CacheLong?: typeof CacheLong; /** Re-export of [`CacheShort`](/docs/api/hydrogen/utilities/cacheshort). */ CacheShort?: typeof CacheShort; /** Re-export of [`CacheCustom`](/docs/api/hydrogen/utilities/cachecustom). */ CacheCustom?: typeof CacheCustom; /** Re-export of [`generateCacheControlHeader`](/docs/api/hydrogen/utilities/generatecachecontrolheader). */ generateCacheControlHeader?: typeof generateCacheControlHeader; /** 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/2025-04/utilities/createstorefrontclient#:~:text=%27graphql%27.-,getPublicTokenHeaders,-(props%3F%3A) for more details. */ getPublicTokenHeaders?: ReturnType< typeof createStorefrontUtilities >['getPublicTokenHeaders']; /** 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/2025-04/utilities/createstorefrontclient#:~:text=storefrontApiVersion-,getPrivateTokenHeaders,-(props%3F%3A) for more details.*/ getPrivateTokenHeaders?: ReturnType< typeof createStorefrontUtilities >['getPrivateTokenHeaders']; /** Creates the fully-qualified URL to your myshopify.com domain. See [`getShopifyDomain` in Hydrogen React](/docs/api/hydrogen-react/2025-04/utilities/createstorefrontclient#:~:text=StorefrontClientReturn-,getShopifyDomain,-(props%3F%3A) for more details. */ getShopifyDomain?: ReturnType< typeof createStorefrontUtilities >['getShopifyDomain']; /** Creates the fully-qualified URL to your store's GraphQL endpoint. See [`getStorefrontApiUrl` in Hydrogen React](/docs/api/hydrogen-react/2025-04/utilities/createstorefrontclient#:~:text=storeDomain-,getStorefrontApiUrl,-(props%3F%3A) for more details.*/ getApiUrl?: ReturnType< typeof createStorefrontUtilities >['getStorefrontApiUrl']; /** The `i18n` object passed in from the `createStorefrontClient` argument. */ i18n?: TI18n; } ``` ### 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). ```ts number ``` * mode The caching mode, generally \`public\`, \`private\`, or \`no-store\`. ```ts 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). ```ts 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). ```ts 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). ```ts number ``` ```ts export interface AllCacheOptions { /** * The caching mode, generally `public`, `private`, or `no-store`. */ mode?: string; /** * 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). */ maxAge?: number; /** * 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). */ staleWhileRevalidate?: number; /** * 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). */ sMaxAge?: number; /** * 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). */ staleIfError?: number; } ``` ### NoStoreStrategy * mode ```ts string ``` ```ts { mode: string; } ``` ### StorefrontMutationOptionsForDocs * displayName The name of the query for debugging in the Subrequest Profiler. ```ts string ``` * headers Additional headers for this query. ```ts HeadersInit ``` * storefrontApiVersion Override the Storefront API version for this query. ```ts string ``` * variables The variables for the GraphQL mutation statement. ```ts Record ``` ```ts { /** The variables for the GraphQL mutation statement. */ variables?: Record; /** Additional headers for this query. */ headers?: HeadersInit; /** Override the Storefront API version for this query. */ storefrontApiVersion?: string; /** The name of the query for debugging in the Subrequest Profiler. */ displayName?: string; } ``` ### StorefrontError * errors ```ts StorefrontApiErrors ``` ```ts { errors?: StorefrontApiErrors; } ``` ### StorefrontApiErrors ```ts JsonGraphQLError[] | undefined ``` ### JsonGraphQLError ```ts ReturnType ``` ### StorefrontQueryOptionsForDocs * cache The cache strategy for this query. Default to max-age=1, stale-while-revalidate=86399. ```ts CachingStrategy ``` * displayName The name of the query for debugging in the Subrequest Profiler. ```ts string ``` * headers Additional headers for this query. ```ts HeadersInit ``` * storefrontApiVersion Override the Storefront API version for this query. ```ts string ``` * variables The variables for the GraphQL query statement. ```ts Record ``` ```ts { /** The variables for the GraphQL query statement. */ variables?: Record; /** The cache strategy for this query. Default to max-age=1, stale-while-revalidate=86399. */ cache?: CachingStrategy; /** Additional headers for this query. */ headers?: HeadersInit; /** Override the Storefront API version for this query. */ storefrontApiVersion?: string; /** The name of the query for debugging in the Subrequest Profiler. */ displayName?: string; } ``` ### 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). ```ts number ``` * mode The caching mode, generally \`public\`, \`private\`, or \`no-store\`. ```ts 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). ```ts 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). ```ts 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). ```ts number ``` ```ts AllCacheOptions ``` ### Examples * #### Example code ##### Description I am the default example ##### JavaScript ```js import {createStorefrontClient} from '@shopify/hydrogen'; import { createRequestHandler, getStorefrontHeaders, } from '@shopify/remix-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 ```ts import {createStorefrontClient} from '@shopify/hydrogen'; // @ts-expect-error import * as serverBuild from 'virtual:react-router/server-build'; import { createRequestHandler, getStorefrontHeaders, } from '@shopify/remix-oxygen'; export default { async fetch( request: Request, env: Record, 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) => 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); }, }; ``` ## Related [![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/hydrogen/utilities/cachenone) [CacheNone](https://shopify.dev/docs/api/hydrogen/utilities/cachenone) [![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/hydrogen/utilities/cacheshort) [CacheShort](https://shopify.dev/docs/api/hydrogen/utilities/cacheshort) [![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/hydrogen/utilities/cachelong) [CacheLong](https://shopify.dev/docs/api/hydrogen/utilities/cachelong) [![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/hydrogen/utilities/cachecustom) [CacheCustom](https://shopify.dev/docs/api/hydrogen/utilities/cachecustom) [![](https://shopify.dev/images/icons/32/pickaxe-1.png)![](https://shopify.dev/images/icons/32/pickaxe-1-dark.png)](https://shopify.dev/docs/api/hydrogen/utilities/inmemorycache) [InMemoryCache](https://shopify.dev/docs/api/hydrogen/utilities/inmemorycache)