Lab - Set Up a Catalyst Project

Introduction

Before proceeding with an exploration of the Catalyst architecture, you will walk through the steps to set up your own local Catalyst project, connected to your BigCommerce store. You’ll be able to use your local installation as a valuable point of reference as we examine Catalyst’s architecture.

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 Catalyst 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. Run the following command, replacing the path to the working directory with your own path.

corepack enable pnpm && pnpm dlx create-next-app@latest -e https://github.com/bigcommerce-edu/lab-catalyst-makeswift-faqs/tree/e-catalyst-start /path/to/working/directory

git clone --branch e-catalyst-start git@github.com:bigcommerce-edu/lab-catalyst-makeswift-faqs.git /path/to/working/directory
cd /path/to/working/directory
pnpm install

2. Run the following commands.

cd /path/to/working/directory
pnpm dlx @bigcommerce/create-catalyst@1.0.1 init

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

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

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

7. Respond to the prompt “Would you like to create a new channel?” with “No.”
8. 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.

npm install -g corepack@latest

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.

2. Browse to the file .catalyst in your project and observe the variables created here.

Unlike the values in .env.local, the values in .catalyst are only used by the CLI installer, not by the storefront application itself, and so these values do not correspond to any environment configuration that must be set up in deployment environments.

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

Step 5: Configure the New Channel

To make sure your Catalyst storefront is fully functional, you’ll need to take care of some minimal configuration on the new channel that was created by the Catalyst installer.

Configure Shipping and Payments

If you want to be able to complete checkout on your Catalyst storefront, you’ll need to make sure you have the appropriate minimal store configuration in place for shipping and payments.

This step is not channel-specific, so if you’ve previously configured shipping and payment options for your store, you won’t need to do any additional setup.

We won’t walk through the details of configuring your store settings, but make sure you have:

• A Shipping Zone that applies to any billing address you will use at checkout
• An enabled Shipping Method on the Shipping Zone
• An enabled test/sandbox Payment Method. (Check the “Enable test credit card payments” option in your Payments Methods settings for the simplest option.)

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 core/.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