Provisioning and upgrading, reimagined

We recently released the first stable version of the Catalyst CLI: a new tool that plays a central role in the provisioning and management of Catalyst, the flagship headless BigCommerce storefront built on Next.js.

While the central entry point for starting development on a Catalyst storefront hasn't changed, the Catalyst CLI brings with it some structure and workflow changes that are important for developers to understand.

The new CLI handles provisioning, but it also installs itself into your project so you can use it for ongoing tasks: linking channels, managing telemetry, and — most notably — upgrading Catalyst itself through a purpose-built command rather than manual merges.

In this article, we'll explore the implications of the Catalyst CLI for developers managing Catalyst projects.

A note on Catalyst Native Hosting: A major driver behind the creation of the Catalyst CLI is its role in managing Catalyst Native Hosting, BigCommerce's first-party hosting platform for Catalyst storefronts. The CLI is the control surface for that platform, and several of its commands exist specifically to serve it.

Catalyst Native Hosting is still in closed beta and is not available for general use. See the documentation to learn more about this pre-release feature. Native hosting itself isn't the focus of this article.

Terminology

Before comparing the old and new workflows, it's worth clearly separating the two npm packages involved. They have similar names, but they play very different roles.

@bigcommerce/create-catalyst

This is the pre-existing package that follows the established npm create <package> convention for scaffolding a project. It was the center of the old workflow, handling both project creation and a handful of project-management subcommands.

It has not gone away. In its new 2.x line, it remains the entry point for creating a Catalyst project — but it is now a thin wrapper for the heavy lifting done by the new Catalyst CLI main package.

@bigcommerce/catalyst

This is the Catalyst CLI itself: the new package, and the core tool going forward. It does the central work during setup, and — unlike its predecessor — it gets installed into your project as a dependency so you can invoke it directly for ongoing tasks.

A naming trap worth internalizing: pnpm create @bigcommerce/catalyst invokes @bigcommerce/create-catalyst, not @bigcommerce/catalyst. That's just how the create convention resolves package names. Once you're inside a project, pnpm catalyst is what invokes the actual Catalyst CLI.

The previous state

Under @bigcommerce/create-catalyst v1.x, the workflow looked like this.

Project setup

Catalyst projects were provisioned with a single command:

pnpm create @bigcommerce/catalyst@latest

Project structure.

To date, Catalyst projects provisioned through the above command were a direct clone of the Catalyst monorepo from GitHub. The Next.js application itself lived in the core directory, alongside the rest of the monorepo's packages and tooling.

Because it was a real clone, your project retained a live Git upstream relationship with the Catalyst repository. That relationship was the mechanism for staying current: upgrading meant pulling from upstream and resolving whatever conflicts arose between the new Catalyst code and your customizations.

You could clone a specific ref with the --gh-ref flag, and pairing that with --reset-main would move the main branch pointer to the cloned ref.

Running other commands

@bigcommerce/create-catalyst was never installed as a project dependency. To run its other subcommands, you executed the package directly with npx or pnpm dlx:

pnpm dlx @bigcommerce/create-catalyst@latest init

That particular command reconnected an existing project to a store and channel.

pnpm dlx fetches a package from the public registry with each run, as opposed to resolving a locally installed package. The @bigcommerce/create-catalyst package is not itself installed as a dependency of a Catalyst project.

The new state

@bigcommerce/create-catalyst v2.x is paired with @bigcommerce/catalyst v1.x, and the division of labor has shifted: create-catalyst is now a thin wrapper around the Catalyst CLI, which performs the actual setup.

The setup command hasn't changed

This deserves emphasis:

pnpm create @bigcommerce/catalyst@latest

That's still the command, and there has been no change to the initial entry point for provisioning a Catalyst project.

A different project structure

The resulting Catalyst project structure differs in a few respects:

• A snapshot copy of core only. Your project is the Next.js application itself, not an entire monorepo with the app buried inside it.

• A fresh local Git repository with a single "Initial commit." This is the same shape you'd get from something like npx create-next-app. There is no upstream relationship with the Catalyst GitHub repository anymore.

• Additional scaffolded tooling. The CLI adds project tooling beyond what exists in core, which means your local project is not 1:1 identical with core at any specific branch or tag of the Catalyst repository.

That last point has a practical consequence worth calling out: the CLI installs @bigcommerce/catalyst itself as a project dependency. That's what makes pnpm catalyst available inside your project.

If you pass the --hosting commerce option, the CLI additionally installs everything needed for native hosting: OpenNext, Cloudflare configuration, and the related tooling. (As noted above, that path is still in closed beta.)

Running commands in a project

Because the CLI is a project dependency, commands can be run directly:

pnpm catalyst channels link

That's the replacement for the old init command — reconnecting an existing project to a store and channel.

Note that it’s still possible to invoke pnpm dlx @bigcommerce/catalyst. As previously mentioned, the difference is that the package to be executed is fetched from the public registry.

The new upgrade workflow

The upgrade story is where the architectural change matters most.

Previously, upgrading Catalyst was a direct Git operation. Your project was a clone of the Catalyst monorepo, so you pulled from upstream, merged, and worked through conflicts by hand. That worked, but it coupled your project's history to Catalyst's history and made every upgrade a manual exercise in Git conflict resolution.

With no upstream relationship, that approach no longer applies. In its place, the Catalyst CLI provides a dedicated command:

pnpm catalyst upgrade <version>

catalyst upgrade performs a 3-way merge between three inputs:

• Your project's base Catalyst version

• The target Catalyst version

• Your project's own custom history

The result is a purpose-built upgrade path rather than a general-purpose Git merge that happens to be pointed at Catalyst. You're no longer maintaining an upstream remote or reasoning about branch pointers just to pick up a new Catalyst release.

Note that a new catalyst property added to package.json contains information about the Catalyst project version and exact GitHub reference (for example, @bigcommerce/catalyst-makeswift@1.10.0). The upgrade command considers this the authoritative source of information about the project version. For existing projects without this property, the upgrade command will attempt to infer the version and add this information.

Note that this upgrade process only affects the Catalyst core code, not dependent packages like @bigcommerce/catalyst-client.  You should periodically upgrade dependencies like this with a typical pnpm upgrade command.

What this means for existing projects

If you already have a Catalyst project built on the monorepo structure, the important message is: you don't need to re-structure.

• Monorepo-based projects still function. Nothing about the 1.0 release breaks an existing installation. Your project continues to build and run as it always has.

• You can adopt the CLI incrementally. Install @bigcommerce/catalyst as a dependency in the core directory of your existing project, and you can begin using pnpm catalyst commands right away:

  • pnpm install @bigcommerce/catalyst@latest

• catalyst upgrade works on monorepo-based projects. The upgrade command supports both newly provisioned projects and those still on the older monorepo structure. This is the most compelling reason for existing projects to pull the CLI in — you get the new upgrade workflow without re-scaffolding. As previously mentioned, upgrade should infer and add version info to package.json. It’s advisable to verify this information.

By its nature, a project provisioned on the monorepo will depend directly on certain modules directly in the packages directory rather than on the publicly available npm package. For example, the previously mentioned dependency @bigcomerce/catalyst-client is declared with the value workspace:^, directly referencing the version in packages/client. Using the new upgrade command rather than the old manual Git workflow means code in packages will not be affected. To avoid confusion from mingling the monorepo structure with the upgrade command, it’s worth considering swapping these dependencies away from the monorepo reference (for example, with pnpm add @bigcommerce/catalyst-client@latest).

Additional details

A few remaining details are worth knowing, whether you're starting fresh or bringing the CLI into an existing project.

The approve-builds step

Newer versions of pnpm require dependencies to be explicitly approved before they can run scripts during installation. The pnpm approve-builds command adds packages to allowBuilds in pnpm-workspace.yaml.

The Catalyst CLI provisions pnpm-workspace.yaml with these approvals unresolved. Until you resolve them, pnpm run dev and pnpm run build will fail and prompt you to complete this step.

Get it out of the way immediately after setup:

pnpm approve-builds --all

Token storage has moved

The store-level OAuth token is no longer kept in a .catalyst file. Instead, a CATALYST_ACCESS_TOKEN is stored in .env.local.

Like the token it replaces, this value is used only by the CLI tool — not at build time and not at runtime. You do not need to configure it in a third-party hosting environment.

Don't confuse it with BIGCOMMERCE_ACCESS_TOKEN. That pre-existing optional variable is separate and still has its own valid use case:

• It can carry its own independent scopes.

• It's the variable used by features requiring REST access, such as the Makeswift Customer Group component.

• It is used at runtime, and it should be configured in a third-party hosting environment.

Notable CLI commands

The Catalyst CLI supports a range of commands — some replacing old @bigcommerce/create-catalyst subcommands, some relating to native hosting, and some entirely new. The full CLI reference covers all of them, but three stand out:

• create: What pnpm create @bigcommerce/catalyst now calls through to. It supports the same options as before, with the exception of the removed --reset-main.

• channel: More capable than the init command it replaces. Use channel link to connect a channel, channel create to create a new one, or channel update to set a channel's site URL to a deployed project hostname.

• upgrade: The 3-way merge described above, and now the correct way to upgrade a Catalyst project.

The final word

The headline change in Catalyst CLI 1.0 is a conceptual one: a Catalyst project is now your project, a clean Next.js application with its own Git history, rather than a fork of someone else's monorepo that you maintain a permanent relationship with.

Your entry point for provisioning a Catalyst project hasn't changed, and existing projects with the monorepo structure can integrate and adopt the Catalyst CLI as well.

This new CLI tool lays the groundwork for more complex workflows to come, including managing Catalyst Native Hosting, and you can find everything else it supports today in the full Catalyst CLI reference.