Choose a version:

createStorefrontClient
utility

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.

Anchor to parametersParameters

HydrogenClientProps<TI18n> & StorefrontClientProps

Anchor to HydrogenClientProps

HydrogenClientProps

Anchor to storefrontHeaders storefrontHeaders: Storefront API headers. If on Oxygen, use getStorefrontHeaders()
Anchor to cache cache Cache: An instance that implements the Cache API
Anchor to storefrontId storefrontId string: The globally unique identifier for the Shop
Anchor to waitUntil waitUntil ExecutionContext: 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 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

CreateStorefrontClientOptions

HydrogenClientProps<TI18n> & StorefrontClientProps

HydrogenClientProps

storefrontHeaders
Storefront API headers. If on Oxygen, use `getStorefrontHeaders()`
```
StorefrontHeaders
```
cache
An instance that implements the [Cache API](https://developer.mozilla.org/en-US/docs/Web/API/Cache)
```
Cache
```
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.
```
ExecutionContext
```
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)
```

{
  /** 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?: ExecutionContext['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);
}

StorefrontHeaders

requestGroupId
A unique ID that correlates all sub-requests together.
```
string
```
buyerIp
The IP address of the client.
```
string
```
cookie
The cookie header from the client
```
string
```
purpose
The purpose header value for debugging
```
string
```

{
  /** A unique ID that correlates all sub-requests together. */
  requestGroupId: string | null;
  /** The IP address of the client. */
  buyerIp: string | null;
  /** The cookie header from the client  */
  cookie: string | null;
  /** The purpose header value for debugging */
  purpose: string | null;
}

Was this section helpful?

Anchor to returnsReturns

Anchor to storefront storefront <TI18n>

CreateStorefrontClientForDocs

storefront
```
StorefrontForDoc<TI18n>
```

{
  storefront?: StorefrontForDoc<TI18n>;
}

StorefrontForDoc

query

The function to run a query on Storefront API.

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

mutate

The function to run a mutation on Storefront API.

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

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

{
  /** The function to run a query on Storefront API. */
  query?: <TData = any>(
    query: string,
    options: StorefrontQueryOptionsForDocs,
  ) => Promise<TData & StorefrontError>;
  /** The function to run a mutation on Storefront API. */
  mutate?: <TData = any>(
    mutation: string,
    options: StorefrontMutationOptionsForDocs,
  ) => Promise<TData & StorefrontError>;
  /** The cache instance passed in from the `createStorefrontClient` argument. */
  cache?: Cache;
  /** Re-export of [`CacheNone`](/docs/api/hydrogen/2024-04/utilities/cachenone). */
  CacheNone?: typeof CacheNone;
  /** Re-export of [`CacheLong`](/docs/api/hydrogen/2024-04/utilities/cachelong). */
  CacheLong?: typeof CacheLong;
  /** Re-export of [`CacheShort`](/docs/api/hydrogen/2024-04/utilities/cacheshort). */
  CacheShort?: typeof CacheShort;
  /** Re-export of [`CacheCustom`](/docs/api/hydrogen/2024-04/utilities/cachecustom). */
  CacheCustom?: typeof CacheCustom;
  /** Re-export of [`generateCacheControlHeader`](/docs/api/hydrogen/2024-04/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/2024-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/2024-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/2024-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/2024-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;
}

StorefrontQueryOptionsForDocs

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

{
  /** The variables for the GraphQL query statement. */
  variables?: Record<string, unknown>;
  /** 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.

mode
The caching mode, generally `public`, `private`, or `no-store`.
```
string
```
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
```
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
```
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
```

AllCacheOptions

StorefrontError

errors
```
StorefrontApiErrors
```

{
  errors?: StorefrontApiErrors;
}

StorefrontApiErrors

JsonGraphQLError[] | undefined

StorefrontMutationOptionsForDocs

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

{
  /** The variables for the GraphQL mutation statement. */
  variables?: Record<string, unknown>;
  /** 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;
}

NoStoreStrategy

mode
```
string
```

{
  mode: string;
}

AllCacheOptions

Override options for a cache strategy.

mode
The caching mode, generally `public`, `private`, or `no-store`.
```
string
```
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
```
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
```
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
```

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;
}

Was this section helpful?

Example code

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);

};

examples

Example code

description

I am the default example

JavaScript

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

import {createStorefrontClient} from '@shopify/hydrogen';
import * as remixBuild from '@remix-run/dev/server-build';
import {
  createRequestHandler,
  getStorefrontHeaders,
} from '@shopify/remix-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: remixBuild,
      mode: process.env.NODE_ENV,
      /* Inject the Storefront client in the Remix context */
      getLoadContext: () => ({storefront}),
    });

    return handleRequest(request);
  },
};