Caching

Catalyst uses several caching mechanisms in Next.js, including request memoization and the Data Cache. They improve performance, reduce redundant requests, and lower rendering costs. For background, see the Next.js caching guide.

Request memoization

Catalyst utilizes Next.js’s request memoization to ensure data is fetched once during the React render cycle, even if requested multiple times within the component tree. This reduces unnecessary network requests, improving performance across your storefront.

When the same data may be fetched more than once during a single page request, Catalyst wraps the async function with React’s cache utility. This memoizes the result and returns the cached value on subsequent calls, as in this product fetcher:

export const getProduct =
  cache(
    async (entityId: number, customerAccessToken?: string) => {
      const { data } = await client.fetch({
        ...
      });
      return data.site.product;
    }
  );

Data Cache

Next.js extends the native fetch API to cache data across requests, allowing cached data reuse until it’s invalidated. This ensures faster response times and reduces the load on external APIs, like the BigCommerce GraphQL Storefront API.

Data Cache behavior is controlled by the fetchOptions parameter passed to the Catalyst client, which your project installs as the @bigcommerce/catalyst-client npm package. This request caches the product query using the default revalidation target:

import { revalidate } from '~/client/revalidate-target';
const { data } = await client.fetch({
  document: ProductQuery,
  fetchOptions: { next: { revalidate } },
});

fetchOptions parameters are passed directly to fetch and follow the standard Next.js conventions. See the Next.js docs on the cache and next.revalidate parameters.

Anonymous vs. customer-specific requests

By default, Catalyst uses the Data Cache for fetch requests for anonymous data, which account for most requests on a typical storefront.

This setup ensures non-unique, repeatable requests benefit from caching while requests affected by customer context are appropriately dynamic.

• Cacheable data: For data that is cacheable, such as product data, fetchOptions is configured to allow caching for guests and disallow it for logged-in customers.
• Non-cacheable data: For data that is never appropriate to cache, such as cart data, fetchOptions is always configured to disallow caching.

This configuration is passed on a per-request basis, so you can configure caching behavior to best suit the needs of a particular fetch.

Cache your own requests

When you write your own API requests, use fetchOptions to cache anonymous data and skip the cache for customer-specific data.

This catalog fetch caches the response for guests and skips the cache for signed-in customers:

import { getSessionCustomerAccessToken } from '~/auth';
import { revalidate } from '~/client/revalidate-target';
const customerAccessToken = await getSessionCustomerAccessToken();
const { data } = await client.fetch({
  document: ProductQuery,
  customerAccessToken,
  fetchOptions: customerAccessToken ? { cache: 'no-store' } : { next: { revalidate } },
});

This cart fetch never caches the response:

import { getSessionCustomerAccessToken } from '~/auth';
const customerAccessToken = await getSessionCustomerAccessToken();
const { data } = await client.fetch({
  document: CartQuery,
  customerAccessToken,
  fetchOptions: {
    cache: 'no-store',
  },
});

Set the cache duration

Data that isn’t customer-specific is cached for 1 hour by default, set by the revalidate property on each fetch. Most functions use the DEFAULT_REVALIDATE_TARGET environment variable. Adjust it to suit your store’s traffic and update frequency:

Rate limiting

BigCommerce GraphQL mutations are rate-limited by the request IP. Catalyst adds the shopper’s IP address to the request headers when a fetch request has a cache value of no-store or no-cache. This keeps one shopper’s requests from counting against another’s rate limit during high traffic.