Introducing the Catalyst CLI

We not too long ago launched the first steady model of the Catalyst CLI: a brand new device that performs a central position within the provisioning and administration of Catalyst, the flagship headless BigCommerce storefront constructed on Subsequent.js.

Whereas the central entry level for beginning growth on a Catalyst storefront hasn’t modified, the Catalyst CLI brings with it some construction and workflow adjustments which can be essential for builders to grasp.

The brand new CLI handles provisioning, however it additionally installs itself into your mission so you should use it for ongoing duties: linking channels, managing telemetry, and — most notably — upgrading Catalyst itself by way of a purpose-built command somewhat than handbook merges.

On this article, we’ll discover the implications of the Catalyst CLI for builders managing Catalyst tasks.

A be aware on Catalyst Native Internet hosting: A serious driver behind the creation of the Catalyst CLI is its position in managing Catalyst Native Internet hosting, BigCommerce’s first-party internet hosting platform for Catalyst storefronts. The CLI is the management floor for that platform, and a number of other of its instructions exist particularly to serve it.

Catalyst Native Internet hosting remains to be in closed beta and isn’t obtainable for common use. See the documentation to be taught extra about this pre-release characteristic. Native internet hosting itself is not the main focus of this text.

Terminology

Earlier than evaluating the previous and new workflows, it is price clearly separating the 2 npm packages concerned. They’ve related names, however they play very completely different roles.

@bigcommerce/create-catalyst

That is the pre-existing bundle that follows the established npm create conference for scaffolding a mission. It was the middle of the previous workflow, dealing with each mission creation and a handful of project-management subcommands.

It has not gone away. In its new 2.x line, it stays the entry level for making a Catalyst mission — however it’s now a skinny wrapper for the heavy lifting executed by the brand new Catalyst CLI foremost bundle.

@bigcommerce/catalyst

That is the Catalyst CLI itself: the brand new bundle, and the core device going ahead. It does the central work throughout setup, and — not like its predecessor — it will get put in into your mission as a dependency so you’ll be able to invoke it straight for ongoing duties.

A naming lure price internalizing: pnpm create @bigcommerce/catalyst invokes @bigcommerce/create-catalyst, not @bigcommerce/catalyst. That is simply how the create conference resolves bundle names. When you’re inside a mission, pnpm catalyst is what invokes the precise Catalyst CLI.

The earlier state

Underneath @bigcommerce/create-catalyst v1.x, the workflow appeared like this.

Venture setup

Catalyst tasks have been provisioned with a single command:

pnpm create @bigcommerce/catalyst@newest

Venture construction.

To this point, Catalyst tasks provisioned by way of the above command have been a direct clone of the Catalyst monorepo from GitHub. The Subsequent.js utility itself lived within the core listing, alongside the remainder of the monorepo’s packages and tooling.

As a result of it was an actual clone, your mission retained a dwell Git upstream relationship with the Catalyst repository. That relationship was the mechanism for staying present: upgrading meant pulling from upstream and resolving no matter conflicts arose between the brand new Catalyst code and your customizations.

You can clone a particular ref with the --gh-ref flag, and pairing that with --reset-main would transfer the foremost department pointer to the cloned ref.

Operating different instructions

@bigcommerce/create-catalyst was by no means put in as a mission dependency. To run its different subcommands, you executed the bundle straight with npx or pnpm dlx:

pnpm dlx @bigcommerce/create-catalyst@newest init

That specific command reconnected an present mission to a retailer and channel.

pnpm dlx fetches a bundle from the general public registry with every run, versus resolving a domestically put in bundle. The @bigcommerce/create-catalyst bundle isn’t itself put in as a dependency of a Catalyst mission.

The brand 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 skinny wrapper across the Catalyst CLI, which performs the precise setup.

The setup command hasn’t modified

This deserves emphasis:

pnpm create @bigcommerce/catalyst@newest

That is nonetheless the command, and there was no change to the preliminary entry level for provisioning a Catalyst mission.

A distinct mission construction

The ensuing Catalyst mission construction differs in just a few respects:

• A snapshot copy of core solely. Your mission is the Subsequent.js utility itself, not a whole monorepo with the app buried inside it.

• A contemporary native Git repository with a single “Preliminary commit.” This is similar form you’d get from one thing like npx create-next-app. There’s no upstream relationship with the Catalyst GitHub repository anymore.

• Further scaffolded tooling. The CLI provides mission tooling past what exists in core, which suggests your native mission isn’t 1:1 an identical with core at any particular department or tag of the Catalyst repository.

That final level has a sensible consequence price calling out: the CLI installs @bigcommerce/catalyst itself as a mission dependency. That is what makes pnpm catalyst obtainable inside your mission.

For those who move the --hosting commerce choice, the CLI moreover installs all the pieces wanted for native internet hosting: OpenNext, Cloudflare configuration, and the associated tooling. (As famous above, that path remains to be in closed beta.)

Operating instructions in a mission

As a result of the CLI is a mission dependency, instructions could be run straight:

pnpm catalyst channels hyperlink

That is the alternative for the previous init command — reconnecting an present mission to a retailer and channel.

Be aware that it’s nonetheless attainable to invoke pnpm dlx @bigcommerce/catalyst. As beforehand talked about, the distinction is that the bundle to be executed is fetched from the general public registry.

The brand new improve workflow

The improve story is the place the architectural change issues most.

Beforehand, upgrading Catalyst was a direct Git operation. Your mission was a clone of the Catalyst monorepo, so that you pulled from upstream, merged, and labored by way of conflicts by hand. That labored, however it coupled your mission’s historical past to Catalyst’s historical past and made each improve a handbook train in Git battle decision.

With no upstream relationship, that method not applies. As a substitute, the Catalyst CLI offers a devoted command:

pnpm catalyst improve

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

• Your mission’s base Catalyst model

• The goal Catalyst model

• Your mission’s personal customized historical past

The result’s a purpose-built improve path somewhat than a general-purpose Git merge that occurs to be pointed at Catalyst. You are not sustaining an upstream distant or reasoning about department pointers simply to choose up a brand new Catalyst launch.

Be aware {that a} new catalyst property added to bundle.json accommodates details about the Catalyst mission model and actual GitHub reference (for instance, @bigcommerce/[email protected]). The improve command considers this the authoritative supply of details about the mission model. For present tasks with out this property, the improve command will try and infer the model and add this info.

Be aware that this improve course of solely impacts the Catalyst core code, not dependent packages like @bigcommerce/catalyst-client.  It is best to periodically improve dependencies like this with a typical pnpm improve command.

What this implies for present tasks

If you have already got a Catalyst mission constructed on the monorepo construction, the essential message is: you needn’t re-structure.

• Monorepo-based tasks nonetheless operate. Nothing concerning the 1.0 launch breaks an present set up. Your mission continues to construct and run because it at all times has.

• You possibly can undertake the CLI incrementally. Set up @bigcommerce/catalyst as a dependency within the core listing of your present mission, and you’ll start utilizing pnpm catalyst instructions instantly:

• catalyst improve works on monorepo-based tasks. The improve command helps each newly provisioned tasks and people nonetheless on the older monorepo construction. That is probably the most compelling purpose for present tasks to drag the CLI in — you get the brand new improve workflow with out re-scaffolding. As beforehand talked about, improve ought to infer and add model information to bundle.json. It’s advisable to confirm this info.

By its nature, a mission provisioned on the monorepo will rely straight on sure modules straight within the packages listing somewhat than on the publicly obtainable npm bundle. For instance, the beforehand talked about dependency @bigcomerce/catalyst-client is said with the worth workspace:^, straight referencing the model in packages/consumer. Utilizing the brand new improve command somewhat than the previous handbook Git workflow means code in packages is not going to be affected. To keep away from confusion from mingling the monorepo construction with the improve command, it’s price contemplating swapping these dependencies away from the monorepo reference (for instance, with pnpm add @bigcommerce/catalyst-client@newest).

Further particulars

A number of remaining particulars are price realizing, whether or not you are beginning contemporary or bringing the CLI into an present mission.

The approve-builds step

Newer variations of pnpm require dependencies to be explicitly accredited earlier than they will run scripts throughout set up. The pnpm approve-builds command provides packages to allowBuilds in pnpm-workspace.yaml.

The Catalyst CLI provisions pnpm-workspace.yaml with these approvals unresolved. Till you resolve them, pnpm run dev and pnpm run construct will fail and immediate you to finish this step.

Get it out of the way in which instantly after setup:

pnpm approve-builds --all

Token storage has moved

The shop-level OAuth token is not saved in a .catalyst file. As an alternative, a CATALYST_ACCESS_TOKEN is saved in .env.native.

Just like the token it replaces, this worth is used solely by the CLI device — not at construct time and never at runtime. You don’t want to configure it in a third-party internet hosting atmosphere.

Do not confuse it with BIGCOMMERCE_ACCESS_TOKEN. That pre-existing optionally available variable is separate and nonetheless has its personal legitimate use case:

• It may possibly carry its personal impartial scopes.

• It is the variable utilized by options requiring REST entry, such because the Makeswift Buyer Group element.

• It is used at runtime, and it ought to be configured in a third-party internet hosting atmosphere.

Notable CLI instructions

The Catalyst CLI helps a spread of instructions — some changing previous @bigcommerce/create-catalyst subcommands, some regarding native internet hosting, and a few completely new. The full CLI reference covers all of them, however three stand out:

• create: What pnpm create @bigcommerce/catalyst now calls by way of to. It helps the identical choices as earlier than, excluding the eliminated --reset-main.

• channel: Extra succesful than the init command it replaces. Use channel hyperlink to attach a channel, channel create to create a brand new one, or channel replace to set a channel’s website URL to a deployed mission hostname.

• improve: The three-way merge described above, and now the right solution to improve a Catalyst mission.

The ultimate phrase

The headline change in Catalyst CLI 1.0 is a conceptual one: a Catalyst mission is now your mission, a clear Subsequent.js utility with its personal Git historical past, somewhat than a fork of another person’s monorepo that you just keep a everlasting relationship with.

Your entry level for provisioning a Catalyst mission hasn’t modified, and present tasks with the monorepo construction can combine and undertake the Catalyst CLI as effectively.

This new CLI device lays the groundwork for extra complicated workflows to return, together with managing Catalyst Native Internet hosting, and yow will discover all the pieces else it helps at present within the full Catalyst CLI reference.