Skip to navigation
DocsStorefrontCatalystGetting Started

Getting Started

There are two ways to set up a Catalyst project: start in the control panel with One-Click Catalyst, or start in your terminal with the Catalyst CLI. Either way, you end up with a Catalyst project you can develop locally. The main differences are where you start and whether Makeswift is included.

Before you start, check the prerequisites. They cover the local tools, store, and control panel permissions both paths need.

One-Click Catalyst

Start in the BigCommerce control panel: Channels → Create Channel → Catalyst.

  • Who it’s for: Marketers and content authors who want to explore Catalyst and Makeswift without writing code.
  • What you get immediately: A hosted preview deployment, plus two connected Makeswift sites (production and development), ready to view and edit right away.
  • Makeswift: Always included.
  • Local code: Not required to get started, but available any time. Your channel’s dashboard gives you a ready-to-run pnpm create command, pre-populated with your channel’s connection details and Makeswift site keys, so running it locally is a copy-paste away.

See One-Click Catalyst for the full walkthrough.

CLI Installation

Start in your terminal:

pnpm create @bigcommerce/catalyst@latest
  • Who it’s for: Developers who want a local project to customize from the start.
  • What you get immediately: A local project on your machine, ready to run with pnpm run dev.
  • Makeswift: Not included by default. Pass --gh-ref @bigcommerce/catalyst-makeswift@latest for a Makeswift-connected project. See Makeswift for how the two variants differ.
  • Local code: Immediately. The CLI creates a new channel (or connects an existing one) and scaffolds the project locally in one step.

See CLI Installation for the full walkthrough.

CLI Installation also works for local development on a storefront you already created with One-Click Catalyst. When the CLI asks whether to create a new channel, choose No and select your One-Click channel. Pass --gh-ref @bigcommerce/catalyst-makeswift@latest to keep its Makeswift integration, and set MAKESWIFT_SITE_API_KEY yourself. The One-Click dashboard’s Start development command does both for you, so it’s usually the quicker way in. See Run locally.

Set up Native Hosting at the same time

Native Hosting, BigCommerce’s own hosting infrastructure, is the recommended way to deploy Catalyst. To set your project up for it from the start, add the --hosting commerce flag to the same command:

pnpm create @bigcommerce/catalyst@latest --hosting commerce

This isn’t a separate setup path. It’s CLI Installation with hosting configured up front, and you can also opt in later from any existing project. See Native Hosting: Getting Started for the full walkthrough.

Choose a setup path

  • Start with One-Click Catalyst if you want to explore Catalyst and Makeswift’s visual editing capabilities first, or if a non-developer on your team needs to design the storefront before development starts. You can always move to local development later.
  • Start with CLI Installation if you’re a developer who wants to begin customizing code immediately, and know whether you want Makeswift’s visual editor as part of your project.

If you’re not sure, One-Click Catalyst is the lower-commitment starting point. It doesn’t require deciding on Makeswift up front, and you can still run the resulting project locally at any time.

Next steps

  • Run a One-Click Catalyst project locally whenever you’re ready to customize code.
  • Deploy to Native Hosting (recommended) or Vercel, and point your domains at the storefront and checkout.
  • Keep your project up to date. Versioning explains Catalyst’s branches and Git tags, and Upgrading shows how to move to a newer release with catalyst upgrade.