# createStorefrontClient

This function extends `createStorefrontClient` from [Hydrogen React](https://shopify.dev/docs/api/hydrogen-react/2023-07/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).

```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);
  },
};

```

```ts
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);
  },
};

```

## Arguments

### CreateStorefrontClientGeneratedType

This function extends `createStorefrontClient` from [Hydrogen React](https://shopify.dev/docs/api/hydrogen-react/2023-07/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).

#### Returns: StorefrontClient<TI18n extends I18nBase>

#### Params:

- options: CreateStorefrontClientOptions<TI18n>
export function createStorefrontClient<TI18n extends I18nBase>(
  options: CreateStorefrontClientOptions<TI18n>,
): StorefrontClient<TI18n> {
  const {
    storefrontHeaders,
    cache,
    waitUntil,
    buyerIp,
    i18n,
    requestGroupId,
    storefrontId,
    ...clientOptions
  } = options;
  const H2_PREFIX_WARN = '[h2:warn:createStorefrontClient] ';

  if (process.env.NODE_ENV === 'development' && !cache) {
    warnOnce(
      H2_PREFIX_WARN +
        'Storefront API client created without a cache instance. This may slow down your sub-requests.',
    );
  }

  const {
    getPublicTokenHeaders,
    getPrivateTokenHeaders,
    getStorefrontApiUrl,
    getShopifyDomain,
  } = createStorefrontUtilities(clientOptions);

  const getHeaders = clientOptions.privateStorefrontToken
    ? getPrivateTokenHeaders
    : getPublicTokenHeaders;

  const defaultHeaders = getHeaders({
    contentType: 'json',
    buyerIp: storefrontHeaders?.buyerIp || buyerIp,
  });

  defaultHeaders[STOREFRONT_REQUEST_GROUP_ID_HEADER] =
    storefrontHeaders?.requestGroupId || requestGroupId || generateUUID();

  if (storefrontId) defaultHeaders[SHOPIFY_STOREFRONT_ID_HEADER] = storefrontId;
  if (LIB_VERSION) defaultHeaders['user-agent'] = `Hydrogen ${LIB_VERSION}`;

  if (storefrontHeaders && storefrontHeaders.cookie) {
    const cookies = getShopifyCookies(storefrontHeaders.cookie ?? '');

    if (cookies[SHOPIFY_Y])
      defaultHeaders[SHOPIFY_STOREFRONT_Y_HEADER] = cookies[SHOPIFY_Y];
    if (cookies[SHOPIFY_S])
      defaultHeaders[SHOPIFY_STOREFRONT_S_HEADER] = cookies[SHOPIFY_S];
  }

  // Deprecation warning
  if (process.env.NODE_ENV === 'development' && !storefrontHeaders) {
    warnOnce(
      H2_PREFIX_WARN +
        '`requestGroupId` and `buyerIp` will be deprecated in the next calendar release. Please use `getStorefrontHeaders`',
    );
  }

  async function fetchStorefrontApi<T>({
    query,
    mutation,
    variables,
    cache: cacheOptions,
    headers = [],
    storefrontApiVersion,
    stackLine,
  }: {stackLine?: string} & (
    | StorefrontQueryOptions
    | StorefrontMutationOptions
  )): Promise<T> {
    const userHeaders =
      headers instanceof Headers
        ? Object.fromEntries(headers.entries())
        : Array.isArray(headers)
        ? Object.fromEntries(headers)
        : headers;

    query = query ?? mutation;

    const queryVariables = {...variables};

    if (i18n) {
      if (!variables?.country && /\$country/.test(query)) {
        queryVariables.country = i18n.country;
      }

      if (!variables?.language && /\$language/.test(query)) {
        queryVariables.language = i18n.language;
      }
    }

    const url = getStorefrontApiUrl({storefrontApiVersion});
    const graphqlData = JSON.stringify({query, variables: queryVariables});
    const requestInit: RequestInit = {
      method: 'POST',
      headers: {...defaultHeaders, ...userHeaders},
      body: graphqlData,
    };

    // Remove any headers that are identifiable to the user or request
    const cacheKey = [
      url,
      {
        method: requestInit.method,
        headers: {
          'content-type': defaultHeaders['content-type'],
          'X-SDK-Variant': defaultHeaders['X-SDK-Variant'],
          'X-SDK-Variant-Source': defaultHeaders['X-SDK-Variant-Source'],
          'X-SDK-Version': defaultHeaders['X-SDK-Version'],
          'X-Shopify-Storefront-Access-Token':
            defaultHeaders['X-Shopify-Storefront-Access-Token'],
          'user-agent': defaultHeaders['user-agent'],
        },
        body: requestInit.body,
      },
    ];

    const [body, response] = await fetchWithServerCache(url, requestInit, {
      cacheInstance: mutation ? undefined : cache,
      cache: cacheOptions || CacheShort(),
      cacheKey,
      shouldCacheResponse: checkGraphQLErrors,
      waitUntil,
      debugInfo: {stackLine, graphql: graphqlData},
    });

    const errorOptions: StorefrontErrorOptions<T> = {
      response,
      type: mutation ? 'mutation' : 'query',
      query,
      queryVariables,
      errors: undefined,
    };

    if (!response.ok) {
      /**
       * The Storefront API might return a string error, or a JSON-formatted {error: string}.
       * We try both and conform them to a single {errors} format.
       */
      let errors;
      try {
        errors = parseJSON(body);
      } catch (_e) {
        errors = [{message: body}];
      }

      throwError({...errorOptions, errors});
    }

    const {data, errors} = body as StorefrontApiResponse<T>;

    if (errors?.length) {
      throwError({
        ...errorOptions,
        errors,
        ErrorConstructor: StorefrontApiError,
      });
    }

    return data as T;
  }

  return {
    storefront: {
      /**
       * Sends a GraphQL query to the Storefront API.
       *
       * Example:
       *
       * ```js
       * async function loader ({context: {storefront}}) {
       *   const data = await storefront.query('query { ... }', {
       *     variables: {},
       *     cache: storefront.CacheLong()
       *   });
       * }
       * ```
       */
      query: <Storefront['query']>((query: string, payload) => {
        query = minifyQuery(query);
        if (isMutationRE.test(query)) {
          throw new Error(
            '[h2:error:storefront.query] Cannot execute mutations',
          );
        }

        const result = fetchStorefrontApi({
          ...payload,
          query,
          stackLine: getCallerStackLine?.(),
        });

        // This is a no-op, but we need to catch the promise to avoid unhandled rejections
        // we cannot return the catch no-op, or it would swallow the error
        result.catch(() => {});

        return result;
      }),
      /**
       * Sends a GraphQL mutation to the Storefront API.
       *
       * Example:
       *
       * ```js
       * async function loader ({context: {storefront}}) {
       *   await storefront.mutate('mutation { ... }', {
       *     variables: {},
       *   });
       * }
       * ```
       */
      mutate: <Storefront['mutate']>((mutation: string, payload) => {
        mutation = minifyQuery(mutation);
        if (isQueryRE.test(mutation)) {
          throw new Error(
            '[h2:error:storefront.mutate] Cannot execute queries',
          );
        }

        const result = fetchStorefrontApi({
          ...payload,
          mutation,
          stackLine: getCallerStackLine?.(),
        });

        // This is a no-op, but we need to catch the promise to avoid unhandled rejections
        // we cannot return the catch no-op, or it would swallow the error
        result.catch(() => {});

        return result;
      }),
      cache,
      CacheNone,
      CacheLong,
      CacheShort,
      CacheCustom,
      generateCacheControlHeader,
      getPublicTokenHeaders,
      getPrivateTokenHeaders,
      getShopifyDomain,
      getApiUrl: getStorefrontApiUrl,
      /**
       * Wether it's a GraphQL error returned in the Storefront API response.
       *
       * Example:
       *
       * ```js
       * async function loader ({context: {storefront}}) {
       *   try {
       *     await storefront.query(...);
       *   } catch(error) {
       *     if (storefront.isApiError(error)) {
       *       // ...
       *     }
       *
       *     throw error;
       *   }
       * }
       * ```
       */
      isApiError: isStorefrontApiError,
      i18n: (i18n ?? defaultI18n) as TI18n,
    },
  };
}


### HydrogenClientProps

### storefrontHeaders

value: `StorefrontHeaders`

Storefront API headers. If on Oxygen, use `getStorefrontHeaders()`

### cache

value: `Cache`

An instance that implements the [Cache API](https://developer.mozilla.org/en-US/docs/Web/API/Cache)

### buyerIp

value: `string`


### requestGroupId

value: `string`


### storefrontId

value: `string`

The globally unique identifier for the Shop

### waitUntil

value: `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.

### i18n

value: `TI18n`

An object containing a country code and language code

### StorefrontHeaders

### requestGroupId

value: `string`

A unique ID that correlates all sub-requests together.

### buyerIp

value: `string`

The IP address of the client.

### cookie

value: `string`

The cookie header from the client

### StorefrontClient

Wraps all the returned utilities from `createStorefrontClient`.

### storefront

value: `Storefront<TI18n>`


### Storefront

Interface to interact with the Storefront API.

### query

value: `<OverrideReturnType = any, RawGqlString extends string = string>(query: RawGqlString, ...options: RawGqlString extends never ? IsOptionalVariables<StorefrontQueries[RawGqlString]> extends true ? [StorefrontQuerySecondParam<RawGqlString>?] : [StorefrontQuerySecondParam<RawGqlString>] : [StorefrontQuerySecondParam<string>?]) => Promise<RawGqlString extends never ? StorefrontQueries[RawGqlString]["return"] : OverrideReturnType>`

The function to run a query on Storefront API.

### mutate

value: `<OverrideReturnType = any, RawGqlString extends string = string>(mutation: RawGqlString, ...options: RawGqlString extends never ? IsOptionalVariables<StorefrontMutations[RawGqlString]> extends true ? [StorefrontMutateSecondParam<RawGqlString>?] : [StorefrontMutateSecondParam<RawGqlString>] : [StorefrontCommonOptions<{ readonly [variable: string]: unknown; }>?]) => Promise<RawGqlString extends never ? StorefrontMutations[RawGqlString]["return"] : OverrideReturnType>`

The function to run a mutation on Storefront API.

### cache

value: `Cache`

The cache instance passed in from the `createStorefrontClient` argument.

### CacheNone

value: `() => NoStoreStrategy`

Re-export of [`CacheNone`](https://shopify.dev/docs/api/hydrogen/2023-07/utilities/cachenone).

### CacheLong

value: `(overrideOptions?: AllCacheOptions) => AllCacheOptions`

Re-export of [`CacheLong`](https://shopify.dev/docs/api/hydrogen/2023-07/utilities/cachelong).

### CacheShort

value: `(overrideOptions?: AllCacheOptions) => AllCacheOptions`

Re-export of [`CacheShort`](https://shopify.dev/docs/api/hydrogen/2023-07/utilities/cacheshort).

### CacheCustom

value: `(overrideOptions: AllCacheOptions) => AllCacheOptions`

Re-export of [`CacheCustom`](https://shopify.dev/docs/api/hydrogen/2023-07/utilities/cachecustom).

### generateCacheControlHeader

value: `(cacheOptions: AllCacheOptions) => string`

Re-export of [`generateCacheControlHeader`](https://shopify.dev/docs/api/hydrogen/2023-07/utilities/generatecachecontrolheader).

### getPublicTokenHeaders

value: `(props?: Partial<Pick<StorefrontClientProps, "contentType">> & Pick<StorefrontClientProps, "publicStorefrontToken">) => Record<string, string>`

Returns an object that contains headers that are needed for each query to Storefront API GraphQL endpoint. See [`getPublicTokenHeaders` in Hydrogen React](https://shopify.dev/docs/api/hydrogen-react/2023-07/utilities/createstorefrontclient#:~:text=%27graphql%27.-,getPublicTokenHeaders,-(props%3F%3A) for more details.

### getPrivateTokenHeaders

value: `(props?: Partial<Pick<StorefrontClientProps, "contentType">> & Pick<StorefrontClientProps, "privateStorefrontToken"> & { buyerIp?: string; }) => Record<string, string>`

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](https://shopify.dev/docs/api/hydrogen-react/2023-07/utilities/createstorefrontclient#:~:text=storefrontApiVersion-,getPrivateTokenHeaders,-(props%3F%3A) for more details.

### getShopifyDomain

value: `(props?: Partial<Pick<StorefrontClientProps, "storeDomain">>) => string`

Creates the fully-qualified URL to your myshopify.com domain. See [`getShopifyDomain` in  Hydrogen React](https://shopify.dev/docs/api/hydrogen-react/2023-07/utilities/createstorefrontclient#:~:text=StorefrontClientReturn-,getShopifyDomain,-(props%3F%3A) for more details.

### getApiUrl

value: `(props?: Partial<Pick<StorefrontClientProps, "storeDomain" | "storefrontApiVersion">>) => string`

Creates the fully-qualified URL to your store's GraphQL endpoint. See [`getStorefrontApiUrl` in  Hydrogen React](https://shopify.dev/docs/api/hydrogen-react/2023-07/utilities/createstorefrontclient#:~:text=storeDomain-,getStorefrontApiUrl,-(props%3F%3A) for more details.

### isApiError

value: `(error: any) => boolean`

Determines if the error is resulted from a Storefront API call.

### i18n

value: `TI18n`

The `i18n` object passed in from the `createStorefrontClient` argument.

### 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

value: `string`

The caching mode, generally `public`, `private`, or `no-store`.

### maxAge

value: `number`

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

### staleWhileRevalidate

value: `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).

### sMaxAge

value: `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).

### staleIfError

value: `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).

### NoStoreStrategy

### mode

value: `string`


### AllCacheOptions

Override options for a cache strategy.

### mode

value: `string`

The caching mode, generally `public`, `private`, or `no-store`.

### maxAge

value: `number`

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

### staleWhileRevalidate

value: `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).

### sMaxAge

value: `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).

### staleIfError

value: `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).

### I18nBase

### language

value: `LanguageCode`


### country

value: `CountryCode`


## Related

- [CacheNone](https://shopify.dev/docs/api/hydrogen/2023-07/utilities/cachenone)
- [CacheShort](https://shopify.dev/docs/api/hydrogen/2023-07/utilities/cacheshort)
- [CacheLong](https://shopify.dev/docs/api/hydrogen/2023-07/utilities/cachelong)
- [CacheCustom](https://shopify.dev/docs/api/hydrogen/2023-07/utilities/cachecustom)
- [InMemoryCache](https://shopify.dev/docs/api/hydrogen/2023-07/utilities/inmemorycache)