Catalyst version 1.7.0 Release Notes

We’re pleased to announce the release of Catalyst 1.7.0, which adds a client-side GraphQL proxy, migrates to a new Private Storefront API token, and makes the root <html lang> attribute locale-aware, alongside several bug fixes. For a full list of changes, see the changeset on GitHub.

Client-side GraphQL proxy

Catalyst now ships a GraphQL proxy that allows allow-listed client-side libraries — such as checkout-sdk-js — to issue GraphQL requests to the BigCommerce Storefront API through your storefront origin. The proxy is implemented in core/proxies/with-graphql-proxy.ts and handles POST /graphql requests that include the x-catalyst-graphql-proxy-requester header. It forwards requests using a dedicated unauthenticated storefront token while still passing through the customer access token for customer-specific catalog data (for example, customer-group pricing).

This unblocks first-party use of checkout-sdk-js on Catalyst without exposing your storefront token to the browser.

Migration

Add a BIGCOMMERCE_STOREFRONT_UNAUTHENTICATED_TOKEN environment variable to your .env.local. This should be a Storefront Private API Token scoped for client-side proxy use (Unauthenticated scope) with minimal permissions.

`BIGCOMMERCE_STOREFRONT_TOKEN` rotation

We are migrating to a new Private Storefront API token. Update the BIGCOMMERCE_STOREFRONT_TOKEN in your .env.local. This variable should now be a Private API Token with the Unauthenticated and Customer scopes. The previous token type is being deprecated; rotating now ensures your storefront keeps working once the older tokens are retired.

For more information about the token types and scopes, see Authenticating requests to the GraphQL Storefront API.

Minor changes

Locale-aware `<html lang>` attribute

The root <html lang> attribute now reflects the active locale instead of being hardcoded to "en". Ownership of <html> and <body> moved to app/[locale]/layout.tsx so lang={locale} is set correctly per request. app/layout.tsx is now a passthrough, and app/not-found.tsx is self-sufficient — it renders its own <html> and <body> — so the branded 404 still works for non-localized requests.

If you have customized app/layout.tsx, app/[locale]/layout.tsx, or app/not-found.tsx, reconcile your changes with the new structure when upgrading.

Bug fixes

Cart discounts row — Cart summary now correctly shows manual discounts applied via the Management Checkout API.
Customer-restricted web pages — Customer-restricted pages are now accessible (and appear in navigation) for authenticated customers. The with-routes proxy is wrapped in auth(), and webpage page-data queries switch to an uncached fetch when a customer token is present.
Brand PLP sort — Brand PLP now defaults to featured sort, honoring the merchant’s configured product order. (TRAC-279)
Breadcrumb cache mutation — Breadcrumb arrays are no longer mutated on cached pages (the React cache() result is now spread before reversing), and truncateBreadcrumbs no longer truncates arrays that are exactly at the target length. ProductReviewSchema is now deferred to client-only rendering to avoid a DOMPurify SSR crash.
DynamicForm — checkbox group required — Fixed a formField.required schema mismatch for checkbox-group fields; the non-required branch was missing .optional().
DynamicForm — hidden fields — Hidden field types now render correctly, fixing a bug where pageEntityId was submitted as NaN on contact form submission.
Gift certificate translation — The gift certificate line item title is now translated in cart, order list, and order details. The order list view now also populates price and totalPrice for gift certificates. (TRAC-276)

Other changes

Request tracing — A stable X-Correlation-ID header is now added to all GraphQL requests. Each page render gets a UUID that persists across all fetches within the same render, making request tracing in server logs much easier.
Translations — Translation strings updated.

@bigcommerce/catalyst-client 1.0.2

Fixed client.fetch so that custom headers passed via fetchOptions.headers properly override the client’s default headers. Headers are now built via a Headers object using .set(), so case-insensitive overrides work as expected.

Release tags

@bigcommerce/catalyst-core@1.7.0
@bigcommerce/catalyst-makeswift@1.7.0

Latest stable: