Skip to navigation
DocsStorefrontCatalystRelease Notes

Catalyst version 1.13.0 release notes

Catalyst 1.13.0 is a minor release. It adds a DISABLE_ANALYTICS environment variable that turns off every analytics integration, cuts repeat ProductViewed events, and retries Storefront GraphQL queries that fail on a transient upstream error. It also fixes the cart shipping estimator and the product page. For a full list of Catalyst changes, see the changeset on GitHub.

Turn off analytics

Set DISABLE_ANALYTICS=true and the storefront sends no analytics:

  • No BigCommerce VisitStarted or ProductViewed events. The catalyst.visitorId, catalyst.visitId, and catalyst.productViews cookies are removed from shoppers who already have them.
  • No Google Analytics.
  • No Script Manager scripts in the Analytics category.
  • No Vercel Analytics or Speed Insights.

Set it at build time. The root layout reads it while prerendering, so changing it on a running deployment has no effect until the next build. See Environment variables.

ProductViewed once per visit

Every product page request with the visit cookies used to send a ProductViewed event, so refreshes and repeat views each cost BigCommerce an uncacheable GraphQL mutation. Catalyst now sends the event once per product per visit.

The products already reported are kept in a new catalyst.productViews cookie, tied to the current visit ID. It has the same sliding 30-minute lifetime as catalyst.visitId, and it’s removed with the other analytics cookies when a shopper declines measurement consent. See Cookies.

Retries for transient GraphQL failures

@bigcommerce/catalyst-client 1.0.4 retries Storefront GraphQL queries that fail on a dropped connection or a 502, 503, or 504. Before, a single upstream failure sent the shopper to the error page. Queries are retried up to twice, after 100ms and 300ms, including when the connection drops while the response body is being read (TypeError: terminated).

Mutations are never retried, since they aren’t idempotent. 4xx responses, GraphQL errors, and aborted requests fail immediately, as before. Each retry logs a console.warn that names the operation, the attempt, and the failure, so recovered failures still show up in server logs:

[BigCommerce] Retrying query GetSite after HTTP 502 (attempt 2 of 3)

Cart and product page fixes

  • Cart shipping estimator: after “View shipping options”, “Add shipping”, or a quantity change, the shipping form now shows the new address, quote, and selected option. It used to keep the previous values until a page reload.
  • Product gallery: selecting a variant with a different default image now updates the gallery.
  • Add to cart: the form now takes the product ID from the product page itself, so editing the hidden id field in devtools or with a script no longer adds a different product. The hidden field stays, so add to cart still works without JavaScript.

Routing cache on Storefront Hosting

On Storefront Hosting, routing lookups that miss the in-process cache are now cached at each Cloudflare location for 5 minutes, instead of Workers KV’s 60-second default. Most of these lookups now take a few milliseconds instead of a trip to central KV storage.

The trade-off is staleness. In the worst case, a storefront status change, such as maintenance mode or launch, can take about 11 minutes to reach a location instead of about 7. It’s usually sooner. Route changes get the same 4 extra minutes on top of their 30-minute window.

Other changes

  • dev and build send the Catalyst User-Agent when fetching the GraphQL schema, matching the storefront’s runtime requests.

Migration

No migration steps are required. DISABLE_ANALYTICS is optional, and no environment variables were renamed or removed.

If you customized any of these files, review the changes when you upgrade. The changeset on GitHub has the code for each one.

  • Analytics: core/proxies/with-analytics-cookies.ts, core/proxies/with-routes.ts, core/components/consent-manager/index.tsx, core/components/consent-manager/_actions/start-visit.ts, and core/app/[locale]/layout.tsx check the new core/lib/analytics/is-analytics-disabled.ts. core/proxies/with-routes.ts and core/proxies/with-analytics-cookies.ts also read and refresh the catalyst.productViews cookie, using the new core/lib/analytics/bigcommerce/product-views.ts.
  • Cart: core/vibes/soul/sections/cart/client.tsx keys ShippingForm on the server’s shipping state.
  • Product page: core/vibes/soul/sections/product-detail/index.tsx keys both ProductGallery usages on the first image, and core/vibes/soul/sections/product-detail/product-detail-form.tsx sets id from the productId prop in onSubmit.
  • Routing cache: core/lib/kv/adapters/cloudflare-kv.ts passes a cacheTtl when reading from the KV namespace.

Release tags

Latest stable: