Guide

Getting started with the CLI

Note

Before you start If you are new to React or Next.js, you may want to start with learn React (opens in a new tab) and learn Next.js (opens in a new tab), then work with the Next.js docs (opens in a new tab).

Prerequisites

Create a new Catalyst project

To create a new Catalyst project, use the Catalyst CLI, which will create a new directory that contains your Catalyst project. You don't need to clone the Catalyst GitHub repository (opens in a new tab) monorepo to use the CLI.

When the CLI connects your project to the BigCommerce store you intend to use, you will be asked to sign in to the subject store using the browser and enter a code provided by the CLI. This step registers your Catalyst project and generates the access tokens the storefront needs to use our APIs. For a more in-depth explanation of authentication mechanisms in Catalyst, see Environment variables in the Catalyst docs and Authenticating Customers (opens in a new tab) on the BigCommerce Dev Center.

We recommend creating a new channel for the Catalyst storefront. For more about channel configuration, see BigCommerce's channels docs (opens in a new tab).

To get started with the CLI, run the following command:

pnpm create @bigcommerce/catalyst@latest

or

npm create @bigcommerce/catalyst@latest

The CLI will take you through the following prompts:

? What is the name of your project? fast-headless-storefront
? Would you like to connect to a BigCommerce store? Y
  Please visit https://login.bigcommerce.com/device/connect and enter the code: <alphanumstr>
 
The code will expire in 30 minutes
 
✔ Device code authorized
 
? Would you like to create a new channel? y
 
? What would you like to name the new channel? Fast Headless Storefront
 
Creating 'fast-headless-storefront' at '/Users/first.last/Documents/projects/fast-headless-storefront'
 
✔ Catalyst template cloned successfully
✔ Catalyst components cloned successfully
 
Using pnpm
 
✔ Dependencies installed successfully
 
... generate GraphQL types ...
 
Success! Created 'fast-headless-storefront' at '/Users/first.last/Documents/projects/fast-headless-storefront'

Run Catalyst

To run your Catalyst storefront locally, cd into the project directory the CLI created, and run the following command:

corepack enable pnpm
 
pnpm run dev

Currently, Catalyst supports npm and pnpm. It does not currently support yarn.

The Catalyst storefront will run on http://localhost:3000.

Configure your Catalyst project

If you want to link your Catalyst project to a different BigCommerce store, repeat the setup process. Run the following command from within the directory that contains your Catalyst project:

npx @bigcommerce/create-catalyst@latest init

If you prefer more control over Catalyst's configuration, you can manually set Catalyst's environment variables. For more information, see Advanced config.

OverviewMonorepo