BigCommerce Catalyst CLI: Monorepo Upgrades in 2026

The BigCommerce Catalyst CLI replaces the monorepo-fork model with a standalone, upgradeable Next.js application with its own Git history. Framework updates are merged for you, and anything that collides with your own changes arrives as ordinary conflict markers rather than a failed merge. Existing monorepo projects can adopt it without re-scaffolding.

Standalone Next.js storefronts replace monorepo forks

In the Introducing the Catalyst CLI announcement (19 August 2026), BigCommerce removed the permanent Git relationship between a storefront and the Catalyst monorepo. Under the legacy scaffolding package (v1.x), scaffolding a storefront with pnpm create @bigcommerce/catalyst@latest cloned the full Catalyst monorepo directly from GitHub into your local environment. Your storefront lived inside a core subdirectory alongside framework packages, shared tooling, and an active Git remote pointing upstream to the BigCommerce Catalyst repository on GitHub.

Maintaining a permanent Git upstream to someone else's monorepo meant resolving conflicts in files your team never touched.

Under the modern CLI workflow, the entry point command remains identical, but the outcome differs. Running pnpm create @bigcommerce/catalyst@latest now provisions a clean snapshot copy of the core directory alone. The CLI initialises a fresh Git repository containing a single Initial commit, with zero remote links to the upstream framework repository. The CLI installs @bigcommerce/catalyst as a local dependency inside your project, turning the storefront into an independent Next.js application.

pnpm create @bigcommerce/catalyst@latest

The documented prerequisites are Node.js 24.x with Corepack-enabled pnpm and Git 2.35.x or later. Under the old create-catalyst 1.x flow, --gh-ref cloned a specific ref and --reset-main moved the main branch pointer to it; the new create keeps the same options except the removed --reset-main.

The package naming trap between scaffolder and CLI

Two distinct npm packages share similar naming conventions but execute completely different responsibilities in your workflow. The first package is @bigcommerce/create-catalyst, which functions as a lightweight scaffolding wrapper in its 2.0.0 release. The second package is @bigcommerce/catalyst, which contains the actual command-line binary and installs directly into your application dependencies.

The naming convention creates an easy trap for developers. Running pnpm create @bigcommerce/catalyst invokes the initialiser package due to npm package resolution rules. Once inside an established project directory, running pnpm catalyst invokes the installed @bigcommerce/catalyst binary. You verify your local environment and inspect active authentication using the CLI's core diagnostic commands:

pnpm catalyst version pnpm catalyst auth login pnpm catalyst auth whoami

Following the 1.0.0 release on 1 July 2026, the 2.0.0 scaffolding release removed standalone init, integration, and telemetry subcommands, delegating project initialisation entirely to catalyst create. In CLI 1.4.1 released on 16 September 2026, catalyst auth login re-verifies stored credentials and carries a rejected token straight on to re-authentication, while --force skips that verification.

Comparing legacy monorepo workflows with the modern CLI

Upgrades previously required developers to fetch upstream commits from the remote repository, merge changes across branches, and manually resolve lockfile and component diffs. If you are weighing theme architecture against a composable frontend, see our breakdown on BigCommerce Stencil vs Catalyst headless. For teams deciding between platform ecosystems, our analysis of Catalyst vs Hydrogen headless covers the framework trade-offs before adopting the standalone BigCommerce command line.

The table below outlines how day-to-day storefront operations shifted between the legacy scaffolder and the modern command line:

How does the automated three-way merge work?

The upgrade workflow executes an automated three-way merge across three distinct code inputs: your storefront's base Catalyst version, the target release version, and your local custom Git history. The command isolates framework updates and stages non-conflicting adjustments automatically.

pnpm catalyst upgrade <version>

As documented in the Catalyst CLI reference, run the command from inside a Catalyst git repository with a clean working tree, and pass --dry-run to generate and display the diff without applying it. Catalyst versions are git tags on the bigcommerce/catalyst repository, not npm packages. If package.json has no catalyst.ref field and --from is not passed, the CLI infers a base version, asks you to confirm it unless --yes is passed, and warns when less than 50% of the inferred base files match your project.

In the BigCommerce builds we maintain, the upgrade step takes most of the review time, so we run --dry-run first and read the diff.

The authoritative reference for this merge engine is the catalyst property stored in your root package.json file. This property records your exact base framework release and Git tag reference, such as @bigcommerce/catalyst-makeswift@1.10.0. In CLI 1.4.1, the upgrade command also preserves CLI-managed npm scripts rather than reverting them to default starter values.

The same 16 September 2026 changelog entry also covers Catalyst 1.12.0, which proxies /.well-known/ucp and /api/ucp/* to BigCommerce so UCP is served on the storefront domain, and no longer sends X-Correlation-ID on cacheable requests, which the changelog notes matters on a product page view of roughly 12 requests.

Upgrading the core framework does not bump external runtime libraries. Dependent packages like @bigcommerce/catalyst-client remain outside the three-way merge, requiring standard package manager commands like pnpm upgrade. Linking storefront channels to BigCommerce environments is equally modular:

pnpm catalyst channels link pnpm catalyst channels create --name "My Store" --locale en --no-sample-data --link pnpm catalyst channels link --channel-id 123

Four rules of thumb before you run any of that on a live store:

How to adopt the new CLI tooling on an existing project in four steps

Existing stores built on the legacy monorepo layout do not require a complete rewrite. Adopting the standalone CLI inside the existing core folder eliminates that drag.

1. Install the CLI package in your core directory. Navigate into core and run pnpm install @bigcommerce/catalyst@latest. You should see the package added to your dependencies in package.json, enabling local pnpm catalyst execution.
2. Approve workspace build scripts. Execute pnpm approve-builds --all from your workspace root. You should see the allowBuilds list in pnpm-workspace.yaml update, resolving execution blocks on dev servers.
3. Verify the catalyst property in package.json. Inspect package.json to confirm that the CLI inferred or added your base release reference (such as @bigcommerce/catalyst-makeswift@1.10.0). You should verify that this pointer matches the actual release tag your project started from.
4. Decouple the client workspace reference if updating APIs. Replace workspace:^ on @bigcommerce/catalyst-client with pnpm add @bigcommerce/catalyst-client@latest. You should see GraphQL queries resolve against the official published npm package rather than internal monorepo paths.

pnpm install @bigcommerce/catalyst@latest pnpm approve-builds --all

Token separation and the pnpm approve-builds trap

In pipelines we set up for BigCommerce stores, a missing build approval in pnpm-workspace.yaml is enough to fail a CI run under the build-script policy of newer pnpm releases.

Newer pnpm releases require dependencies with lifecycle scripts to receive explicit permission before execution. If the approvals are missing from pnpm-workspace.yaml, pnpm run dev and pnpm run build can fail before the dev server starts. Running pnpm approve-builds --all registers the required build permissions and clears the blockage.

Authentication tokens also shifted locations. The legacy store-level OAuth token formerly located in a local .catalyst file now lives in .env.local under the CATALYST_ACCESS_TOKEN variable. This key is used strictly by the CLI for administrative tasks; it is not the token the running storefront uses. Do not confuse it with BIGCOMMERCE_ACCESS_TOKEN, which remains a runtime secret carrying independent scopes for REST-driven features like the Makeswift Customer Group component.

BigCommerce Native Hosting in closed beta

The decoupled layout also feeds BigCommerce Native Hosting, a first-party hosting target for Catalyst storefronts. Passing the --hosting commerce flag during project scaffolding installs OpenNext, Cloudflare configuration and related tooling. Native Hosting remains in closed beta and is not available for general production workloads.

On 1 July 2026, @bigcommerce/catalyst 1.0.0 introduced unified build, deployment and logging commands to manage this infrastructure, with catalyst domains and catalyst logs query added in the same changelog as create-catalyst 2.0.0. You configure production builds, launch local previews, and manage secrets using dedicated subcommands:

pnpm catalyst build --env-path .env.prod pnpm catalyst start pnpm catalyst deploy --secret BIGCOMMERCE_STORE_HASH=<YOUR_STORE_HASH> --secret BIGCOMMERCE_STOREFRONT_TOKEN=<YOUR_STOREFRONT_TOKEN> pnpm catalyst env add BIGCOMMERCE_STORE_HASH=<YOUR_STORE_HASH> BIGCOMMERCE_STOREFRONT_TOKEN=<YOUR_STOREFRONT_TOKEN>

For debugging live environments, the CLI supports real-time request streaming and historical log filtering. The documented examples query the last 24 hours with a limit of 20 entries, or the last 2 days as raw JSON:

pnpm catalyst logs tail --format request pnpm catalyst logs query --since 24h --level-min error --limit 20 pnpm catalyst logs query --since 2d --format json

The CLI also includes catalyst domains for configuring production custom domains (a newly added domain starts in a pending verification state, and --wait polls for up to 5 minutes), while channels update sets your store's channel site URL directly to your deployed application hostname.

Before you commit

Before you run an upgrade on your primary production storefront, branch your repository and verify your package manager bindings. If your existing project relies on workspace-linked packages such as @bigcommerce/catalyst-client, decouple those dependencies to public npm versions before running your first three-way merge. Keep your deployment targets steady on your current infrastructure while Native Hosting completes its closed beta testing.

If your team is running an enterprise multi-storefront architecture and struggling with upstream merge conflicts or complex headless upgrades, talk to us about our BigCommerce development work.

Our first step is an audit of your repository structure and package bindings before any upgrade is run.