> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# 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](https://github.com/bigcommerce/catalyst/blob/main/core/CHANGELOG.md#170).

## 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](/developer/api-reference/rest/admin/authentication-apis/storefront-api-tokens/private-api-token/create-private-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](/developer/docs/storefront/guides/graphql-storefront-api/authentication).

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

* [**@bigcommerce/catalyst-core@latest**](https://github.com/bigcommerce/catalyst/releases/tag/%40bigcommerce%2Fcatalyst-core%40latest)
* [**@bigcommerce/catalyst-makeswift@latest**](https://github.com/bigcommerce/catalyst/releases/tag/%40bigcommerce%2Fcatalyst-makeswift%40latest)