Local Development

This guide assumes you used the One-Click Catalyst workflow by following the Getting Started guide. If not, see the Manual installation docs.

After completing the Getting Started guide, you should have a sandbox instance of Catalyst. You'll also have two Makeswift sites:

  • Production - connected to the deployed Catalyst instance
  • Development - connected to http://localhost:3000

The development site is the one you'll use when developing locally. By running the source code locally, developers will have the ability to customize their storefront in any way including:

Lastly, you'll want to push the source code into a your own Github repository. Let's see how to run the code locally and create your own Github repository.

Prerequisites

Before you begin, ensure you have met the prerequisites listed below on your local machine.

Node.js version 20.x

Catalyst currently supports Node.js version 20.x (click here to download Node.js (opens in a new tab))

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 (opens in a new tab))

Git version 2.35.x or later

Click here to download Git (opens in a new tab)

A GitHub account

You can sign up for a free GitHub account on the official GitHub signup page (opens in a new tab).

Running locally

In the BigCommerce dashboard for your Catalyst channel, you'll see a few steps under the Complete Setup section. The Start development section includes a terminal command to run in your local environment.

Cataylst storefront dashboard showing a complete setup section which includes a terminal command.

This command will do several things:

  • Clone the Catalyst repository
  • Set all environment variables
  • Set the main branch to match the git ref that was deployed to the BigCommerce partner sandbox account (more on versioning)
  • Set the upstream remote variable to https://github.com/bigcommerce/catalyst.git
ℹ️

NOTE: The MAKESWIFT_SITE_API_KEY environment variable is the API key for your development Makeswift site.

After running the command in your terminal, start your development server with the following command:

pnpm dev

By default, Catalyst will run at http://localhost:3000. This is also the URL that the development site in Makeswift is connected to. From here, you can open the development Makeswift site in your browser.

⚠️

If you're locally running project runs at a different port than 3000 you'll need to update the Host URL property in Makeswift to match.

As you make changes in the code, you'll be able to see them reflected in real time. Note that some changes may require a refresh of the page.

Creating a Github repository

Now that you have the code running locally, you'll want to move the code to your own source control repository. In this example, we'll use Github, but feel free to use any Git provider you'd like.

Go to Github (opens in a new tab) and create a new repository. GitHub will prompt you to choose a name for your repository. For the purposes of this guide, we'll refer to name of the repository as <YOUR_REPOSITORY_NAME>. You should replace <YOUR_REPOSITORY_NAME> in all of the commands below with your actual repository name.

After you've created your Github repository, you can connect you local repository to the remote repository by running the following command:

    git remote add origin git@github.com:<YOUR_GITHUB_USERNAME>/<YOUR_REPOSITORY_NAME>.git

Then, you can push your changes to the remote repository by running:

    git push -u origin main

Next Steps

You now have your own Github repository that you can continue to iterate on. When you're ready to publish your site, refer to our Deploying docs for next steps.

Getting StartedVersioning