DocsStorefrontCatalystGetting Started

CLI Installation

The Catalyst CLI is the developer-first way to set up a project. It scaffolds a new Catalyst codebase on your machine, connects it to a BigCommerce store, and initializes a fresh Git repository for you. To create a Catalyst channel with the REST Management API instead, see Manually create a Catalyst channel.

Prerequisites

Make sure you’ve met the prerequisites before you continue.

Create the project

1

Run the Catalyst CLI

pnpm create @bigcommerce/catalyst@latest

The CLI walks you through naming your project, authenticating with your BigCommerce store via your browser, and connecting a channel. It then installs dependencies and initializes a Git repository in your new project directory.

By default, the CLI scaffolds @bigcommerce/catalyst-core, which has no Makeswift integration. For a Makeswift-connected project, pass the --gh-ref flag:

pnpm create @bigcommerce/catalyst@latest --gh-ref @bigcommerce/catalyst-makeswift@latest

See Makeswift for how the two variants differ.

2

Run the development server

From your new project directory, start the development server:

cd <your-project>
pnpm run dev

The following table lists localhost URLs with the default ports. When a port is unavailable, Catalyst uses the next available port. For example, if 3000 is in use, Catalyst runs on 3001.

ProcessURL with port
Catalyst storefronthttp://localhost:3000

Project structure

The CLI copies only the Catalyst storefront application (the core directory of the Catalyst repository) into your project directory. Your project is a standalone Next.js application, not a copy of the full Catalyst monorepo.

Push to a remote repository

Your CLI-scaffolded project already has a Git repository initialized locally, so you only need to connect it to a remote. These steps use GitHub, but any Git provider works.

  1. Create a new repository on GitHub. Don’t initialize it with a README, license, or .gitignore, since your project already has a commit history.

  2. From your project directory, add the repository as a remote and push:

    git remote add origin git@github.com:<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME>.git
    git push -u origin HEAD

    HEAD pushes whichever branch you’re on, so this works whether Git named your initial branch main or master.

Next steps