BigCommerce x Catalyst

Catalyst is the composable, fully customizable headless ecommerce storefront framework for BigCommerce built with Next.js and BigCommerce’s GraphQL Storefront API.

Catalyst is a fully functional BigCommerce storefront that is optmized for SEO, accessibility, and performance. Catalyst is designed to take care of the essentials so you can focus your efforts on building your brand and adding those special features that take storefronts to the next level.

To see Catalyst in action, check out the working demo.

Catalyst and Makeswift can be used in conjunction, or independent of one another. While they are separate solutions, both are built to be heavily integrated with one another. This guide serves as a supplement to the documentation available on the Catalyst Getting Started documentation.

Prerequisites

1. Node.js version 20.x

Catalyst currently supports Node.js version 20.x (click here to download Node.js)

2. Corepack-enabled pnpm

Node.js version 20.x ships with Corepack by default; you should be able to run corepack enable from your terminal to meet this prerequisite (more information on the official Node.js Corepack documentation)

3. Git version 2.35.x or later:

Click here to download Git

4. A BigCommerce store or sandbox

You can create a trial store or spin up a developer sandbox to meet this prerequisite. If you already have a BigCommerce store, that will work fine too.

5. A Makeswift workspace.

If you have not created a Makeswift workspace, do so ahead of time here.

6. Permission to create API accounts on your store

In order to allow Catalyst to authenticate with your BigCommerce store, you’ll need to make sure that your user account on the subject store has been granted the Create store-level API Accounts permission detailed in our documentation on High-Risk Permissions. If you are the assigned store owner of the store, you have these permissions implicitly.

7. A GitHub account

You can sign up for a free GitHub account on the official GitHub signup page.

Steps

1

Run the CLI

Use the Catalyst CLI to pull down the latest version of the main branch of the monorepo. The CLI will:

1. Clone the Catalyst monorepo.
2. Add a remote pointing to the upstream Catalyst repository.
3. Enable Corepack so that you can use pnpm as your package manager.
4. Install Catalyst Dependencies.
5. Set up environment variables.

This command will prompt you to name your project, as well as connect it to a BigCommerce store.

pnpm create @bigcommerce/catalyst@latest

Change into your new project directory:

cd <YOUR_PROJECT_NAME>

2

Fork the Catalyst repo

Next, you’ll want to fork the Catalyst repo. This will enable you to create and mange your own deployments. Navigate to the Catalyst repo and click Fork at the top of the page.

GitHub will prompt you to choose a name for your fork; for the purposes of this guide, we’ll refer to the name of the fork as <YOUR_FORK_NAME>. You should replace <YOUR_FORK_NAME> in all of the commands below with your actual fork name.

Back in your terminal, add your fork as a remote to your local repository:

git remote add origin [e-mail]:<YOUR_GITHUB_USERNAME>/<YOUR_FORK_NAME>.git

3

Fetch the Makeswift integration branch

The Makeswift Catalyst integration is available in a branch in the upstream GitHub repository.

git fetch upstream integrations/makeswift
git checkout -b integrations/makeswift upstream/integrations/makeswift

Push this branch to your forked repository on Github.

git push -u origin integrations/makeswift

4

Update environment variables

Update the root .env.local file with your Site API Key located under your Host settings in Makeswift.

Add the key to your .env.local file with the following key name:

MAKESWIFT_SITE_API_KEY=<YOUR_API_KEY>

Save your .env.local file.

5

Run your development server

Install dependencies to match the current branch

pnpm i

Start the development server

pnpm dev

6

Update host settings

Within the Makeswift Site Settings, update the host to the URL of your locally running project. By default, it should be http://localhost:3000.

7

Explore

Now that you have a running Catalyst website within Makeswift, you can begin custom development on your Catalyst application and visually edit your pages in Makeswift.

We recommend familiarizing yourself with Makeswift by going through the Product Quickstart before you begin any development. There are some out-of-the-box components that leverage the best of Next.js that can help drive some decisions around what custom components you’ll want to create.

When you do identify custom components you’ll need to create, checkout out our our App Router or Pages Router developer documents to learn how to register your components with Makeswift.