DocsStorefrontCatalystGetting Started

Upgrading

catalyst upgrade brings an existing Catalyst project forward to a newer release. It downloads your project’s current base version and the target version, then applies a 3-way merge between that base, your local changes, and the target. Changes that don’t conflict with your customizations are staged automatically; anything that does conflict is left as standard Git conflict markers for you to resolve.

Prerequisites

Before running the upgrade:

  • A clean Git working tree. The merge writes in place, so any uncommitted changes in your project would be indistinguishable from the upgrade itself. Commit or stash them first.
  • @bigcommerce/catalyst installed as a dependency. This is the CLI package that provides the upgrade command. Projects scaffolded with a recent version of catalyst create already have it. If yours doesn’t — most commonly legacy monorepo-structure projects created before the CLI existed — install it first.
  • A catalyst.ref field in package.json. This tells the CLI which version your project is currently on, so it knows what to diff against. If it’s missing, the CLI infers a base version from your package name and version and asks you to confirm before continuing (skip the prompt with --yes). If the inferred base is wrong, pass --from <ref> to set it explicitly — for example, --from @bigcommerce/catalyst-core@1.6.0.

Run the upgrade

Run the command from inside your Catalyst project:

1

Run the upgrade command

pnpm catalyst upgrade

pnpm exec catalyst upgrade works the same way. With no arguments, this upgrades to the latest tag in the same package family your project is already on (for example, @bigcommerce/catalyst-core or @bigcommerce/catalyst-makeswift). Pass a specific version to target it instead:

pnpm catalyst upgrade 1.8.0

To move to a different integration family — for example, adding Makeswift to a project that started as core-only — pass the full tag with --ref:

pnpm catalyst upgrade --ref @bigcommerce/catalyst-makeswift@1.7.0
2

Preview before applying (optional)

Run with --dry-run first to see the diff between your base version and the target without changing any files:

pnpm catalyst upgrade --dry-run

This is worth doing on any upgrade where you’ve made substantial customizations, since it gives you a sense of the conflict surface before committing to the merge.

3

Resolve conflicts

Without --dry-run, the CLI merges the target version into your project and stages every file that merged cleanly. Files with conflicts are left as unmerged entries with standard <<<<<<< ours / ======= / >>>>>>> theirs markers, the same as any Git merge — most editors’ merge tooling picks them up automatically. The upgrade never aborts partway through, even if every file conflicts.

4

Commit your changes

Resolve each conflicted file, then stage and commit as usual:

git add .
git commit -m "Upgrade Catalyst to 1.8.0"
5

Install dependencies

The upgrade never runs your package manager for you. If it touched package.json — including a clean dependency bump with no conflict — run an install before you start testing:

pnpm install

Upgrade one minor version at a time rather than jumping straight to the latest release, especially on a project with significant customizations. The merge diffs your base version directly against the target, so a larger version gap means a larger diff and more surface area for conflicts.

Incremental upgrades also keep each merge closer to what the CLI expects. It flags a warning when fewer than about 50% of the base version’s files still match your project unmodified. That warning signals the assumed base version no longer reflects your project, and it gets more likely the more versions you cross in a single jump.

Dependency versions

catalyst upgrade keeps your @bigcommerce/catalyst* dependencies (including @bigcommerce/catalyst-client) current as part of the same merge that updates everything else. As long as your project pins one of these packages to an ordinary semver range, a version bump shipped in the target release is applied automatically — or flagged as a conflict if you’d deliberately pinned that dependency to something else. There’s no separate step or command for this; it’s handled the same way as any other package.json change.

Projects still on the workspace protocol

If your project references a Catalyst package with a workspace:^ specifier instead of a semver range, the upgrade can’t resolve it the same way — normalizing only one side of that comparison would manufacture a conflict rather than resolve one. Instead, after the merge completes, the CLI prints a table of affected packages and offers to migrate them:

The most common place this comes up is on legacy monorepo-structure projects — their packages/ directory holds a local copy of the dependency, so workspace:^ resolves to it instead of the published package.

Catalyst dependencies still using the workspace protocol (1):
  @bigcommerce/catalyst-client   workspace:^ → ^1.0.2
Replace them with the published versions?
  • Accepting (or passing --yes) rewrites the dependency to the published version your target release shipped, so future upgrades can keep it current the normal way.
  • Declining leaves the workspace:^ specifier in place. Your project continues resolving that dependency to your local packages/ copy rather than the published package, and it stays on the migration prompt’s opt-in path — catalyst upgrade doesn’t touch a workspace: specifier once one exists, so it won’t move on a future upgrade either unless you accept the prompt then.

--dry-run never shows this prompt as accepted — it’s an opt-in step that only runs when the merge is actually applied.

If your CLI itself is out of date

The CLI that runs the upgrade can’t upgrade itself through the same merge, so it checks the npm registry directly (best-effort — a registry hiccup never fails the upgrade). If a newer version is available, you’ll see an advisory at the end of the run:

Your Catalyst CLI is behind (1.1.0 → 1.2.0). Update it with `pnpm add -D @bigcommerce/catalyst@1.2.0`.

Run the suggested command, then continue with your next upgrade as usual.

Legacy monorepo-structure projects

Catalyst historically shipped as a monorepo clone, with core/ nested under a repo root alongside sibling packages/ directories. Newer projects are flat, with the same contents at the repo root. catalyst upgrade detects either layout automatically by locating the package.json that carries a catalyst field, so upgrading a monorepo-structure project doesn’t require restructuring it first.

The one thing a monorepo-structure project needs before its first upgrade is the CLI itself — these projects predate @bigcommerce/catalyst existing as a package, so it was never installed as a dependency. Add it before running upgrade:

pnpm add -D @bigcommerce/catalyst

After that, catalyst upgrade works the same as it does on a flat project.

Next steps