Lab - Getting Started with Catalyst

In this exercise, 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.

The Catalyst Storefront

The process used to create your new storefront, referred to as One-Click Catalyst, has provisioned several things:

• The dedicated storefront channel.
• A deployment to a Vercel preview environment. Remember that Catalyst is a headless storefront application, which must be deployed on its own. The initial deployment to a sandbox URL like store-*.catalyst-sandbox-vercel.store allows you to immediately explore the functioning Catalyst front-end, but once you begin customizing, it’s time to deploy to your own hosting.
• A Makeswift site. The “Edit in Makeswift” button launches the builder for the Makeswift site corresponding with the storefront and controlling various visual content on it.
• Sample data including BigCommerce sample products and categories, as well as pre-configured content in Makeswift.

Note that the new channel page includes a CLI command in the “Complete Setup” section that can be used to immediately set up a local project connected to your new storefront. We’ll be using a version of the command with different options in the next step, but the principle is the same.

Step 2: Install the Catalyst Project

1. At the command line, navigate to the directory one level above the desired location of your project and run the Catalyst installer.

corepack enable pnpm && pnpm create @bigcommerce/catalyst@latest --gh-ref @bigcommerce/catalyst-makeswift@1.6.3

2. Respond to the prompt “What is the name of your project?” The value you provide will be the name of the directory created for the project.

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.

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.

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