@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@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 `UserAc...

@bigcommerce/catalyst-makeswift@1.9.0

Minor Changes

• Pulls in changes from the @bigcommerce/catalyst-core@1.9.0 release. For more information about what was included in the @bigcommerce/catalyst-core@1.9.0 release, see the changelog entry.

@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.

@bigcommerce/create-catalyst@2.0.0

Major Changes

• #3077 a45ab43 Thanks @jorgemoya! - Reduce create-catalyst to a thin wrapper that delegates to catalyst create. pnpm create catalyst / npx create-catalyst still scaffold a project — now by invoking @bigcommerce/catalyst under the hood — so the scaffolding UX is unchanged. The standalone init, integration, and telemetry subcommands are removed; use catalyst channel link and catalyst telemetry from the consolidated CLI instead.

Patch Changes

• Updated dependencies [a45ab43]:
  • @bigcommerce/catalyst@1.0.0

@bigcommerce/catalyst@1.0.0

Major Changes

• #3077 a45ab43 Thanks @jorgemoya! - Introducing the Catalyst CLI (@bigcommerce/catalyst) — a single command-line tool for scaffolding, building, and deploying your Catalyst storefront to BigCommerce's Native Hosting infrastructure.

  Highlights

  • Scaffold a storefront — catalyst create downloads a clean, standalone project (flattened from core/, workspace: dependencies resolved to published versions, fresh git repo) via tarball extraction and connects it to your BigCommerce store. The package manager is auto-detected from npm_config_user_agent.
  • Browser-based authentication — Run catalyst auth login to authenticate via an OAuth device code flow. Credentials are stored locally in .bigcommerce/project.json for use by all subsequent commands. CI/CD environments can use --store-hash and --access-token flags or environment variables instead.
  • Project & channel management — Create, link, and list BigCommerce infrastructure projects with catalyst project, and connect storefront channels with catalyst channel.
  • Build & deploy — catalyst build runs the OpenNext Cloudflare build pipeline (deriving the Wrangler compatibility_date dynamically) and generates deployment artifacts. catalyst deploy bundles, uploads, and deploys your storefront with real-time progress streaming. Pass runtime secrets with --secret KEY=VALUE; environment variables are auto-detected as deploy secrets.
  • Persisted deployment env vars — Manage deployment environment variables across deploys with catalyst env (list and remove; values are masked).
  • Custom domains — Add, list, check the status of, and remove custom domains for a Native Hosting project with catalyst domains.
  • Local preview — catalyst start launches a local Cloudflare Workers preview of your built storefront via the OpenNext adapter.
  • Live & historical logs — catalyst logs tail streams real-time application logs with color-coded levels and auto-reconnect; catalyst logs query retrieves historical logs.
  • In-place upgrades — catalyst upgrade upgrades a project to a newer version via a resilient 3-way merge (git merge-tree, falling back to per-file git merge-file), producing resolvable conflict markers instead of ever aborting.
  • Smart credential resolution — Configuration is resolved in priority order: CLI flags → --env-file → process environment variables → .bigcommerce/project.json.
  • Telemetry — Anonymous usage telemetry with session and correlation IDs for support. Opt out anytime with catalyst telemetry disable.

  Commands

  Command	Description
  catalyst create	Scaffold and connect a Catalyst storefront to your BigCommerce store
  catalyst auth	Authenticate, sign out, and verify stored credentials
  catalyst project	Create, link, and list infrastructure projects
  catalyst channel	Connect a storefront channel to your project
  catalyst build	Build your Catalyst project for deployment
  catalyst deploy	Build and deploy to BigCommerce Native Hosting
  catalyst env	Manage persisted deployment environment variables
  catalyst domains	Manage custom domains for a Native Hosting project
  catalyst start	Start a local Cloudflare Workers preview
  catalyst logs	Stream live logs and query historical logs
  catalyst upgrade	Upgrade a project to a newer version via 3-way merge
  catalyst version	Display CLI, Node.js, and platform info
  catalyst telemetry	View or change telemetry collection status

  Getting started

  cd core
  pnpm add @bigcommerce/catalyst@latest @opennextjs/cloudflare@1.17.3
  pnpm catalyst auth login
  pnpm catalyst project create
  pnpm catalyst deploy --secret BIGCOMMERCE_STORE_HASH=<hash> --secret BIGCOMMERCE_STOREFRONT_TOKEN=<token>

  For full documentation, see the Native Hosting Overview and CLI Reference.

@bigcommerce/create-catalyst@1.1.0

Minor Changes

• #3055 854aab5 Thanks @jorgemoya! - Deprecate the create-catalyst integration command. It now prints a deprecation warning when invoked and is hidden from --help. The command builds integration patches by diffing git tags, which won't work once Catalyst projects are distributed as tarballs (no git history) — it will be replaced by the forthcoming catalyst upgrade command. The command still functions for now; full removal will follow in a future major version.

@bigcommerce/catalyst-makeswift@1.8.0

Minor Changes

• #2913 097eea7 Thanks @agurtovoy! - Enable interaction-mode site navigation in Makeswift builder

• Pulls in changes from the @bigcommerce/catalyst-core@1.8.0 release. For more information about what was included in the @bigcommerce/catalyst-core@1.8.0 release, see the changelog entry.

Patch Changes

• #2950 4d511dc Thanks @agurtovoy! - Fix 404 error on switching between localized Makeswift pages with locale-specific paths when TRAILING_SLASH=true

@bigcommerce/catalyst-core@1.8.0

Minor Changes

• #3024 3cec674 Thanks @mfaris9! - Honor the merchant's Tax Display setting (Inc., Ex., or Both) from the BigCommerce control panel across PDP, PLP, search, compare, and home. When set to Both, prices render stacked with (Inc. Tax) and (Ex. Tax) labels, including sale strike-throughs per line.

  Migration

  For forks that can't rebase cleanly: pricing was refactored end-to-end to support inc/ex tax variants and a Both mode (PricingFragment, pricesTransformer, Price types, page-data settings queries, analytics helpers). See PR #3024 for the full diff.

• #3015 15e365a Thanks @mfaris9! - Consume merchant-configured per-locale URL subfolders from the BigCommerce Storefront GraphQL API (Locale.path). The locale that sits at the bare root URL (/) is derived from the CP configuration: if the default locale has no path, it sits at root; otherwise, if exactly one non-default locale has no path, that one sits at root; otherwise every locale gets a prefix. Locales with a path use it; locales without a path fall back to their locale code.

Patch Changes

• #3031 874e332 Thanks @Tharaae! - Display backorder information for variants on PDP.

• #3033 8bc379d Thanks @jorgemoya! - Fix broken images in WYSIWYG content (web pages, blog posts, product description and warranty). Images uploaded through the Control Panel editor are stored as store-root-relative WebDAV paths (/content/... and /product_images/...) that 404 on the headless storefront domain; they are now rewritten to absolute BigCommerce CDN URLs.

• #3056 2c99731 Thanks @jorgemoya! - Add a catalyst field to core/package.json (catalyst.version and catalyst.ref) that tracks the true Catalyst version independently of the top-level version, which merchants may repurpose for their own deploy tagging. The backend user-agent now reports catalyst.version (falling back to version for projects created before the field existed), and the release pipeline keeps the field in sync on each version bump.

• #3035 b4215f0 Thanks @jorgemoya! - Scope the consent manager cookie (c15t-consent) to the current host instead of the top-level domain. Previously crossSubdomain: true caused the cookie to be set on the root domain (e.g. .example.com) for stores running on a sub-domain, so it appeared on both the root domain and the sub-domain. Removing it makes the cookie host-only, so it now exists only on the sub-domain the store runs on.

• #3046 5034ea3 Thanks @chanceaclark! - Gate catalyst.visitorId, catalyst.visitId, and currencyCode cookies behind shopper consent. The visitor and visit cookies now require measurement consent and the currency preference cookie requires functionality consent. When consent is absent, existing analytics cookies are deleted on the next request. When measurement consent is granted mid-session, a new startVisit server action sets the cookies and fires the server-side visitStartedEvent immediately rather than waiting for the next full-page navigation.

• #3047 1ab2c82 Thanks @chanceaclark! - Make authjs.session-token and authjs.anonymous-session-token browser-session cookies (no Expires attribute) to satisfy Essential cookie classification requirements.

  What changed

  Anonymous session token: anonymousSignIn no longer sets maxAge on the cookie. Without it, Next.js omits Max-Age/Expires and the cookie becomes a session cookie that the browser drops when it closes.

  Auth session token: Auth.js v5 unconditionally writes Expires on the session token cookie and provides no config option to suppress it. Two post-processing steps strip the attribute:

  • proxies/with-auth.ts — strips Expires from Set-Cookie response headers on every page request.
  • auth/index.ts — wraps signIn and updateSession to re-set the cookie via cookies().set() without Expires immediately after Auth.js writes it, covering the sign-in and session-update paths that middleware cannot reach.

  Max-Age=0 (used by Auth.js for cookie deletion on sign-out) is intentionally left intact.

  Migration

  If you have a custom maxAge on anonymousSignIn: The default 7-day maxAge has been removed. If your app relies on anonymous sessions persisting across browser restarts, add it back in your own anonymousSignIn call:

  cookieJar.set(anonymousCookieName, jwt, {
    httpOnly: true,
    sameSite: 'lax',
    secure: useSecureCookies,
    maxAge: 60 * 60 * 24 * 7, // restore 7-day persistence if needed
  });

  If you already have your own Expires-stripping workaround: Remove it. The middleware regex in with-auth.ts and the patchSessionTokenCookies wrapper in auth/index.ts now handle this centrally. Leaving both in place will cause redundant cookie writes.

  If you import signIn or updateSession directly from auth/index.ts: No change needed — the signatures are identical. The exports are now thin async wrappers that call the Auth.js originals and then patch any session token cookies written during the call.

• #3058 94c503e Thanks @bc-svc-local! - Update translations.

• #3048 226f2f3 Thanks @bc-svc-local! - Update translations.

@bigcommerce/catalyst-makeswift@1.7.0

Minor Changes

• Pulls in changes from the @bigcommerce/catalyst-core@1.7.0 release. For more information about what was included in the @bigcommerce/catalyst-core@1.7.0 release, see the changelog entry.