Version Packages (canary)

[github-actions]

This PR was opened by the Changesets release GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to canary, this PR will be updated.

Releases

@bigcommerce/catalyst@1.1.0

Minor Changes

• #3111 9565d76 Thanks @jorgemoya! - catalyst now reads the API host from CATALYST_API_HOST (renamed from BIGCOMMERCE_API_HOST) and resolves it with the same precedence as other credentials: --api-host flag > CATALYST_API_HOST > .bigcommerce/project.json apiHost > default api.bigcommerce.com. Breaking: the BIGCOMMERCE_API_HOST environment variable is no longer read — set CATALYST_API_HOST instead.

• #3110 5ca4c61 Thanks @jorgemoya! - Add the catalyst debug command, which prints a diagnostic report (CLI version, runtime, the project's package manager, project/config state, telemetry correlation ID, and which key files exist) to include when filing a bug report. Credentials and environment variables are resolved across the same chain a build uses (process.env > .env.local > .env > .bigcommerce/project.json) and reported by name and source only — secret values are never printed. Use --json for machine-readable output.

• #3084 aadaf27 Thanks @jorgemoya! - Add the catalyst domains claim command, which claims ownership of a custom domain that is already in use on another store. When you try to add a domain bound to a different store, catalyst domains add now prints the ownership-verification TXT record to publish; after publishing it, run catalyst domains claim <domain> to release the domain from the other store and bind it to your project.

• #3089 8d9f9a9 Thanks @jorgemoya! - Add the catalyst domains transfer command, which moves a custom domain from one project to another project in the same store (the same-store counterpart to domains claim). Pass --to-project-uuid <uuid> to target a specific project, or omit it to pick the destination interactively from your store's projects. When catalyst domains add fails because the domain is already bound to another project in the store, it now points you at the exact domains transfer command to move it instead of surfacing the raw API error.

• #3098 05f600a Thanks @jorgemoya! - Env-file loading is now scoped to catalyst build and catalyst deploy — the only commands that need storefront environment variables (for the build). Previously .env.local was auto-loaded globally from the current working directory (but .env was not), which was surprising, inconsistent, and affected commands that don't use those variables. Now build and deploy auto-load .env.local and .env from the current directory (with .env.local taking precedence, and neither overriding your real environment), and you can point at a specific file with --env-path <path>. No other command reads env files.

  Migration: if you relied on env vars being auto-loaded for a command other than build/deploy, set them in your shell environment or pass the relevant flags instead. For a build with an env file outside the project directory, use catalyst deploy --env-path ../.env.local.

Patch Changes

• #3105 552cfb5 Thanks @jorgemoya! - Add a --wrangler-version <version> flag to catalyst build and catalyst deploy so developers can build against a Wrangler version or dist-tag other than the pinned default. When omitted, the build uses the pinned default as before (and the flag is ignored by deploy --prebuilt, which skips the build). The value is validated to look like a version or dist-tag before it's interpolated into the wrangler@<version> spec.

• #3102 fea7b30 Thanks @jorgemoya! - Add the @bigcommerce/catalyst CLI to a newly created project's devDependencies instead of dependencies. The CLI is a build-time tool (it only backs the build/start/deploy npm scripts) and is never imported at runtime, so it doesn't belong in runtime dependencies.

• #3095 27373e8 Thanks @jorgemoya! - Validate channel names before creating a channel. catalyst create and catalyst channel create now reject names containing unsupported characters (such as an apostrophe in "Bob's Store") with a clear message that names the offending input and lists the allowed characters — letters, numbers, spaces, hyphens, and underscores — instead of surfacing an opaque API error. The interactive prompt validates as you type, and an invalid --name flag fails fast.

• #3099 b4e5952 Thanks @jorgemoya! - Unify the device-code login UX across auth login, create, and the channel commands. The CLI now waits for you to press Enter before opening the browser and best-effort copies the one-time code to your clipboard so you can paste it directly (the code is still printed as a fallback). Non-interactive/CI runs skip the prompt and open directly.

• #3097 e3e5ab2 Thanks @jorgemoya! - Fail catalyst build/catalyst deploy fast with a clear, actionable error when required environment variables (BIGCOMMERCE_STORE_HASH, BIGCOMMERCE_STOREFRONT_TOKEN, BIGCOMMERCE_CHANNEL_ID, AUTH_SECRET) aren't loaded, instead of surfacing a raw OpenNext/Next.js build stack trace. The check also runs on the plain next build fallthrough (non-Commerce-Hosting projects), not just the Commerce Hosting pipeline. The message names the missing variables and explains that the build auto-loads .env.local and .env from the current directory (or pass --env-path <path> to load a file from elsewhere).

• #3107 0d42b12 Thanks @jorgemoya! - Fix the dependency install step hanging indefinitely during catalyst project link and the catalyst deploy first-run setup. nypm runs the install through tinyexec, which in silent mode drains the child's stdout to completion before it reads stderr; pnpm floods stderr with Node warnings (on Node 26, thousands of File descriptor N opened in unmanaged mode lines), filling the stderr pipe buffer while tinyexec is still on stdout, so pnpm blocks writing and the install deadlocks. The install now runs the child with NODE_NO_WARNINGS (and pins COREPACK_ENABLE_DOWNLOAD_PROMPT off) so stderr never fills. The link/deploy setup paths also now detect the project's actual package manager from its lockfile instead of always forcing pnpm.

• #3096 c1d0f3d Thanks @jorgemoya! - project create now shows the actionable "Infrastructure Projects API not enabled — contact support to join the beta" guidance when the API responds 404, matching the existing 403 handling, instead of a cryptic Failed to create project: Not Found.

• #3094 bf58b13 Thanks @jorgemoya! - Give the CLI readable, actionable errors when a BigCommerce API returns a 4xx or 5xx. A shared HTTP-error helper now turns a failed response into a clear message: it prefers the API's own reason (detail/title/field errors) and, when the body is empty or unparseable, falls back to curated copy for the status class. Client (4xx) errors are treated as user-actionable and print without the "share this Correlation ID with BigCommerce support" framing, while server (5xx) errors keep it. This replaces the raw ... failed: <status> <statusText> throws across the channel, project, deploy, logs, and auth API paths.

• #3088 ce03afb Thanks @jorgemoya! - Stop framing clear, user-actionable CLI errors as bugs to report. Validation errors, not-found and not-enabled responses, conflicts, and bad command input now print just the message and exit, instead of appending a Correlation ID and a "share this with BigCommerce support" prompt. That framing is now reserved for genuine server-side (5xx) failures and unexpected errors. Applies across the domains, project, channel, logs, and auth commands via a shared UserActionableError type.

• #3100 07cd41c Thanks @jorgemoya! - The CLI now follows .env.example as the source of truth when writing .env.local. Generated env files preserve the documented ordering and per-key comment blocks, render documented-but-unsupplied keys as blank/default active keys, and append any CLI-only variables in a clearly separated trailing section. Existing .env.local values are reconciled rather than clobbered on re-runs (e.g. channel link), so user-set values are preserved while newly documented keys are added in their canonical position.

@bigcommerce/create-catalyst@2.0.1

Patch Changes

• Updated dependencies [552cfb5, 9565d76, fea7b30, 5ca4c61, 27373e8, b4e5952, e3e5ab2, aadaf27, 8d9f9a9, 0d42b12, c1d0f3d, bf58b13, 05f600a, ce03afb, 07cd41c]:
  • @bigcommerce/catalyst@1.1.0

@bigcommerce/catalyst-core@1.9.0

Minor Changes

• #3104 25d6471 Thanks @parthshahp! - Respect default product search sort and product category sort settings from the control panel.

• #3083 2b7f2cc Thanks @jorgemoya! - Display product videos (YouTube) on the PDP in a dedicated section below the primary product content, mirroring the Stencil/Cornerstone layout. The Storefront GraphQL API exposes product videos as a { title, url } pair (Product.videos); Catalyst now fetches them and renders a featured player with a thumbnail strip (clicking a thumbnail swaps the featured video) using lite-youtube-embed — a lightweight facade that loads the YouTube player only when a shopper clicks. A small getYouTubeId() helper extracts the video id from the watch URL the API returns.

  Migration

  Additive — no breaking changes; existing PDP markup, the image gallery, and image pagination are unchanged. Forks adopting this manually need to:

  • add the lite-youtube-embed dependency;
  • request videos(first: 25) { edges { node { title url } } } on the PDP product query (product/[slug]/page-data.ts);
  • stream those videos and render the new ProductVideos section below ProductDetail (product/[slug]/page.tsx);
  • allow i.ytimg.com/vi/** in next.config.ts images.remotePatterns for poster thumbnails.

• #3057 a763acc Thanks @bc-vivekaggarwal! - Wire promotion callouts into PDP and PLP pages using live data from the Storefront GraphQL API (featuredPromotions on the Product type).

  • PDP: stacked callout boxes render inline below the price, one per active promotion.
  • PLP (category, brand, search): each product card shows its first promotion inline below the price; if there are multiple, a "+N more" label appears within the same callout.

Patch Changes

• #3076 c6b3b07 Thanks @chanceaclark! - Fix Account Settings failing to save for customers when a merchant-defined required custom customer field exists. BigCommerce revalidates required custom fields on every updateCustomer call, so Account Settings now renders and resubmits those fields (mirroring the existing Register/Address form-field support) instead of only supporting first name, last name, email, and company.

• #3106 4975333 Thanks @jorgemoya! - Disable caching for the webpage sidebar navigation and route/raw-page resolution when a customer access token is present, so customer-only navigation links and pages aren't leaked to (or hidden from) other visitors via a shared cache.

• #3109 8256b46 Thanks @jordanarldt! - Keep the cart's locale in sync when a shopper switches their storefront locale. Previously, changing the locale only updated the storefront URL and left the cart on its original locale. The locale switcher now calls the new updateCartLocale Storefront GraphQL mutation to update the active cart in place before navigating, mirroring the existing currency-switch behavior. This mutation is currently gated behind a store-side feature flag; until it's enabled, updateCartLocale returns null and the switch is a no-op.

• #3103 d09f8dc Thanks @chanceaclark! - Coalesce rapid cart line item quantity and delete clicks into at most one in-flight server action. Quantity buttons now update an optimistic pending intent that flushes a single absolute-quantity update intent after a short debounce (replacing the per-click increment/decrement intents), and deletes are serialized instead of queueing unboundedly. This prevents the serial server-action queue buildup that could lock up navigation on the cart page, and unifies cart revalidation on revalidateTag.

  The cart section is now keyed by cart entityId only (previously entityId-version) and renders line items from the revalidation-refreshed cart prop. Remounting on every mutation swallowed clicks landing during the DOM swap and could drop queued actions, leaving the summary skeletons and checkout button stuck in a pending state until hard refresh.

  Each quantity/delete control is now its own progressive-enhancement form that posts a real absolute quantity or delete request to the server action; JS intercepts the submit to route through the coalescing dispatcher, but the buttons keep working (as full page round-trips) before hydration or if the app bundle fails to load.

  Also fixes the checkout button getting stuck spinning forever if its navigation is cancelled (Esc, "Stay" on the leave-page prompt, a flaky connection). The URL-string checkout action previously awaited a promise that never resolved, leaving retry clicks queued behind a dead action; it now settles after a short timeout and on bfcache restore, re-enabling the button as a retry.

• #3087 cb7d025 Thanks @jairo-bc! - Respect the Blog visibility setting (Control Panel > Storefront > Blogs) in the footer navigation. The Blog link no longer appears in the footer's "Navigate" section when Blog visibility is turned off.

• #3101 f60aea6 Thanks @bc-svc-local! - Update translations.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
catalyst	Ready	Preview, Comment	Jul 16, 2026 6:23pm

[github-actions]

Bundle Size Report

Comparing against baseline from 5ca4c61 (2026-07-16).

No bundle size changes detected.

[github-actions]

Unlighthouse Performance Comparison — Vercel

Comparing PR preview deployment Unlighthouse scores vs production Unlighthouse scores.

Summary Score

Aggregate score across all categories as reported by Unlighthouse.

	Prod Desktop	Prod Mobile	Preview Desktop	Preview Mobile
Score	90	93	92	94

Category Scores

Category	Prod Desktop	Prod Mobile	Preview Desktop	Preview Mobile
Performance	75	86	83	77
Accessibility	95	95	95	92
Best Practices	100	100	100	100
SEO	88	100	100	100

Core Web Vitals

Metric	Prod Desktop	Prod Mobile	Preview Desktop	Preview Mobile
LCP	3.7 s	4.2 s	2.7 s	4.6 s
CLS	0.037	0	0.001	0
FCP	1.2 s	1.2 s	1.1 s	1.1 s
TBT	0 ms	0 ms	10 ms	0 ms
Max Potential FID	40 ms	50 ms	60 ms	50 ms
Time to Interactive	3.7 s	4.2 s	3.5 s	4.7 s

Full Unlighthouse report →