Lab - Set Up Catalyst and Makeswift

Introduction

In this lab, you’ll set up a new Catalyst project with Makeswift enabled.

Using Catalyst as our storefront style is key to the future labs and the custom development of components. This route gives you full control over the Next.js application that renders your components, which is what makes building custom React components for the editor possible.

In this lab, you will:

• Create a new Catalyst storefront and Makeswift site
• Install Catalyst and run a local dev server

Prerequisites

• A BigCommerce sandbox store or trial store, or a full production store, with an available storefront seat
• A control panel user with the following permissions: “Create Store-level API accounts,” “Install applications,” “Launch applications”, “Create Channels” (Learn about high-risk permissions)
• A command-line interface on your local machine
• Node.js 24 or later
• The pnpm package manager
• Git CLI

For following along in the code in future lessons, it’s also helpful to make sure you have a code editor, like VS Code, to open your Makeswift project once installed.

Step 1: Create a Catalyst Storefront

1. Log into your BigCommerce store control panel.
2. Navigate to Channel Manager (or Channels) and Create channel.
3. In the list of channel types, choose “Create” next to the “Catalyst” type.
4. Enter a storefront name, select “Use sample data,” and click “Create” to finalize the storefront.

Once the provisioning process is begun, you will need to wait for the initial deployment to complete.

Proceed with the following steps after deployment is complete.

5. Click the “View storefront” button to view your hosted preview storefront.
6. Click the “Edit in Makeswift” button to launch the Makeswift editor and confirm that you are able to edit your pages.

Step 2: Install the Catalyst Project

Rather than start your custom code from scratch, you’ll be starting from a Catalyst codebase that already has certain boilerplate in place, in preparation for subsequent labs.

1. Install degit.

npm install -g degit

2. Run the following command, replacing the path to the working directory with your own path.

degit https://github.com/bigcommerce-edu/lab-catalyst-makeswift-faqs#e-makeswift-start /path/to/working/directory

3. Navigate to the new project working directory and initialize a Git repository for your project.

cd /path/to/working/directory
git init
git add .
git commit -m "Initial project files"

4. Install the project dependencies.

corepack enable pnpm && pnpm install

5. Run the following command.

pnpm catalyst channel link

You will eventually be presented with the BigCommerce device authorization URL - https://login.bigcommerce.com/device/connect - and a unique code.

6. Press Enter or manually browse to the given URL and log into your BigCommerce account.
7. If you have multiple stores associated with your account, choose the store you want to associate with your Catalyst project.
8. Enter the code from your command line output, and click “Next.”
9. Allow the required permissions.

With authorization completed, back at the command line, there will be new installation steps to complete.

10. Respond to the prompt “Would you like to create a new channel?” with “No.”
11. Select the storefront channel you previously created in the control panel.

The completion of the installation may take a few minutes. The installer will install the Catalyst code files into your local project, install all npm dependencies, and configure your store information and credentials.

Step 3: Run the Dev Server

1. Navigate to the new project working directory.

cd /path/to/catalyst/project

2. Run the dev server.

pnpm run dev

3. Browse to the URL displayed in the command line output. (Usually http://localhost:3000)

Provided that you chose to install sample data when creating your Catalyst storefront, you should see a fully populated storefront home page. Your local site should be nearly identical to your hosted preview environment, although as previously noted, there may be differences between the installed codebase and the deployed preview.

4. If you are not still logged in the Makeswift editor, return to Channel Manager (or Channels) in your BigCommerce control panel, click on your storefront channel, and click”Edit in Makeswift.”
5. In the Makeswift editor, use the site switcher in the upper left corner to switch to the “Dev” site (for example, “My Catalyst Storefront (Dev)”) and confirm that the localhost site successfully loads in the editor.

Step 4: Examine the Local Configuration

1. Open the file .env.local in your new project and observe the environment variables that have been created by the installer.

Unlike most of the other values in .env.local, CATALYST_ACCESS_TOKEN is only used by the CLI itself — for example, to authorize commands like channel link — and is never read by the storefront application at build time or runtime. Because of this, it does not need to be set in any deployment environment.

2. Browse to the /admin path on your local storefront to visit your BigCommerce control panel.

The Local Dev Server and Cache

At various points while working in your local project, you may need to restart your dev server or clear the Next.js or Turborepo caches. Below is an example set of steps to do all three.

1. Stop the local dev server (CTRL-C at the command line).
2. Clear the contents of the Next.js cache directory. This is located at .next/cache in your project working directory.
3. Clear the contents of the Turborepo cache directory. This is located at .turbo/cache in your project working directory.
4. Start the dev server again.

pnpm run dev