DocsStorefrontCatalystRelease Notes

Catalyst version 1.12.2 release notes

Catalyst 1.12.2 is a patch release. It fixes carts leaking across channels on multi-channel storefronts, and adds two meta tags that identify how a storefront is hosted and which channel it serves. For a full list of Catalyst changes, see the changeset on GitHub.

One cart per channel

Catalyst stored the shopper’s cart as a single cart ID in the session cookie, with no channel attached. The cart page, the header cart count, and checkout all read that one ID. After a shopper switched to another channel, they saw the previous channel’s cart and could check it out there.

The cookie now stores a cartIds map that pairs each channel ID with that channel’s cart ID. getCartId, setCartId, and clearCartId in core/lib/cart read and write only the current channel’s entry. The current channel is resolved the same way as requests to the BigCommerce API: the channel mapped to the active locale in channels.config.ts, or BIGCOMMERCE_CHANNEL_ID when the locale has no mapping.

Login and logout

  • Login sends the BigCommerce API only the cart for the channel the shopper signed in on. BigCommerce can merge it with the account’s saved cart for that channel. The rest of the guest map carries over to the customer session, and each channel’s cart is shown when the shopper signs in from that channel.
  • Logout sends the BigCommerce API the cart for the channel the shopper signed out from. The new guest session starts without the other channels’ carts, and keeps the signed-out channel’s cart only when BigCommerce returns one.

Existing sessions

Sessions created before this release store only the single cartId, and they keep working. A page render can’t write cookies, so the first page load still shows that cart on any channel. The session moves to the cartIds map on the shopper’s first cart action, such as adding an item, changing a quantity, checking out, logging in, or registering, or when they switch language in the header. The cart is stored under the channel of the page where that action ran.

The cartId field stays in the cookie next to the map, so older cookies and a rollback to 1.12.1 keep the shopper’s cart.

Hosting and channel meta tags

Catalyst already renders platform and store_hash meta tags so a storefront can identify itself from its page source. This release adds two more:

  • channel_id is the storefront’s BigCommerce channel ID.
  • hosting is native on Catalyst Native Hosting, vercel on Vercel, and other everywhere else. It reads the CATALYST_HOSTING environment variable, which catalyst deploy sets to native, and falls back to Vercel’s VERCEL variable.
<meta name="channel_id" content="1">
<meta name="hosting" content="native">

Migration

No migration steps are required. Existing sessions keep their cart, and no environment variables were added or renamed.

If you customized the cart or auth code, review these changes when you upgrade:

  • getCartId, setCartId, and clearCartId accept an optional channelId. Calls without one use the current channel, so existing calls keep working.
  • The session user gains a cartIds field next to cartId, and the password credentials provider accepts an optional channelId.
  • signOut exported from core/auth accepts an optional channelId, which picks the cart that logout sends to BigCommerce.

Release tags

Latest stable: