Catalyst Client

The Catalyst Client is how a Catalyst storefront calls BigCommerce’s GraphQL Storefront API. Import the instance your project configures:

import { client } from '~/client';

The client builds request URLs, sets request headers, and parses JSON responses for you. It’s published as the @bigcommerce/catalyst-client npm package, and your project configures an instance of it in client/index.ts, using the store hash, storefront token, and channel ID from your environment variables.

Client configuration

client/index.ts creates the client with createClient(). You can change these options to adjust how every request is made:

There’s no hook that runs after a response is received. To act on failures, use onError or catch the errors that fetch() throws.

Methods

• fetch(): runs any query or mutation in the GraphQL Storefront API.

• fetchSitemapIndex(channelId?: string): fetches the XML sitemap index (/xmlsitemap.php) for a channel and returns it as text. When you omit channelId, it uses the same channel resolution as fetch().

Fetch

The following sections describe the fetch() method.

Parameters

Request headers

The fetch method automatically sets the following headers:

• "Content-Type": "application/json"
• "Authorization": "Bearer <storefrontToken>"
• "User-Agent": <backendUserAgent>
• "X-Bc-Customer-Access-Token": <customerAccessToken> (when customerAccessToken is provided)
• "X-Bc-Error-On-Invalid-Customer-Access-Token": "true" (when validateCustomerAccessToken is true)
• "X-BC-Trusted-Proxy-Secret": <secret> (when the BIGCOMMERCE_TRUSTED_PROXY_SECRET environment variable is set)

Catalyst’s beforeRequest hook in client/index.ts also adds:

• "Accept-Language": <locale> (when the current locale is known)
• "X-Forwarded-For" and "True-Client-IP", set to the shopper’s IP address, and "X-Correlation-ID". These are added only to uncached requests (cache: 'no-store' or cache: 'no-cache'), because request headers are part of the Next.js Data Cache key, and per-request values would make every cached lookup miss.

Headers you pass in fetchOptions.headers override any of these.

Retries

Queries that fail with a 502, 503, or 504 response, or with a network error such as a dropped connection, are retried up to two more times, after 100 ms and then 300 ms. Each retry logs a warning. Mutations are never retried, because they aren’t safe to repeat.

Return value

The fetch method returns a promise that resolves to a response object containing the requested data. The response follows the structure defined in the GraphQL query.

• Return Type: Promise<BigCommerceResponse<TResult>>

  The BigCommerceResponse type wraps the actual data returned from the API, where TResult represents the expected shape of the response data.

  Inside BigCommerceResponse, the data field holds the actual data returned by the GraphQL API, which matches the structure of the query or mutation you executed.
  
  

• Errors: the method throws when the HTTP request fails, or when the API returns GraphQL errors that the errorPolicy says to throw. See Error handling.

Examples

Get customer orders (authenticated request)

import { client } from '~/client';
import { graphql } from '~/client/graphql';
import { revalidate } from '~/client/revalidate-target';
import { getSessionCustomerAccessToken } from '~/auth';
const GET_CUSTOMER_ORDERS = graphql(`
  query getCustomerOrders {
    customer {
      orders {
        edges {
          node {
            entityId
            orderNumber
            status
          }
        }
      }
    }
  }
`);
const customerAccessToken = await getSessionCustomerAccessToken();
const response = await client.fetch({
  document: GET_CUSTOMER_ORDERS,
  customerAccessToken,
  fetchOptions: customerAccessToken ? { cache: 'no-store' } : { next: { revalidate } },
});

Get product reviews (unauthenticated request)

import { client } from '~/client';
import { graphql } from '~/client/graphql'; // A utility function for handling GraphQL queries
const GET_PRODUCT_REVIEWS_QUERY = graphql(`
  query getProductReviews($productIds: [Int!]) {
    site {
      products(entityIds: $productIds) {
        edges {
          node {
            reviews {
              edges {
                node {
                  author {
                    name
                  }
                  title
                  text
                }
              }
            }
          }
        }
      }
    }
  }
`);
const response = await client.fetch({
  document: GET_PRODUCT_REVIEWS_QUERY, // GraphQL query
  variables: { productIds: [101, 202] },  // Query variables
  fetchOptions: { cache: 'no-store' }, // Optional fetch options
});
console.log(response.data);

The example output in the console:

{
  "site": {
    "products": {
      "edges": [
        {
          "node": {
            "reviews": {
              "edges": [
                {
                  "node": {
                    "author": {
                      "name": "John Doe"
                    },
                    "title": "Great product",
                    "text": "This product exceeded my expectations!"
                  }
                },
                {
                  "node": {
                    "author": {
                      "name": "Jane Smith"
                    },
                    "title": "Good value",
                    "text": "Worth the price, very satisfied."
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}

To flatten edges and node wrappers, use the removeEdgesAndNodes() utility exported by @bigcommerce/catalyst-client.

Error handling

fetch() checks the HTTP response for you and throws if something goes wrong, so wrap calls in try/catch rather than inspecting the response. @bigcommerce/catalyst-client exports these error classes:

import { BigCommerceAPIError, BigCommerceGQLError } from '@bigcommerce/catalyst-client';
try {
  const response = await client.fetch({ document: GET_PRODUCT_REVIEWS_QUERY, variables });
  return response.data;
} catch (error) {
  if (error instanceof BigCommerceAPIError) {
    // HTTP failure: inspect error.status
  } else if (error instanceof BigCommerceGQLError) {
    // GraphQL errors: inspect error.errors
  }
  throw error;
}

Before throwing a GraphQL error, the client calls its onError hook. By default, Catalyst’s hook redirects the shopper to sign out when a query fails with a BigCommerceAuthError, so an expired customer session is cleared automatically.

Logging

You can log the request’s operation name, type, and execution time to the console, along with the query complexity.

Logging is on by default outside production, and off in production. To change this, set the CLIENT_LOGGER environment variable to true or false. When logging is enabled, the fetch method invokes the requestLogger() function internally to capture and log the information.