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.
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.
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 rotationWe 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.
<html lang> attributeThe 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.
with-routes proxy is wrapped in auth(), and webpage page-data queries switch to an uncached fetch when a customer token is present.featured sort, honoring the merchant’s configured product order. (TRAC-279)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.required — Fixed a formField.required schema mismatch for checkbox-group fields; the non-required branch was missing .optional().pageEntityId was submitted as NaN on contact form submission.price and totalPrice for gift certificates. (TRAC-276)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.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.@bigcommerce/catalyst-core@1.7.0@bigcommerce/catalyst-makeswift@1.7.0Latest stable: