> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Lab - Set Up Catalyst and Makeswift

Plan: Composable Developer

Lesson 5 of 22 · 30 min

> **Info**
>
> Note that the starter codebase for these labs picks up where the labs from Catalyst Core left off. If you have a local project as set up in these labs, you can skip this lab and simply start the dev server in your existing example project:
>
> *pnpm run dev*

## 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](/developer/docs/overview/sandboxes) or [trial store](https://www.bigcommerce.com/essentials/), 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](https://support.bigcommerce.com/s/article/User-Permissions#highrisk))
* A command-line interface on your local machine
* Node.js 24 or later
* The [pnpm](https://pnpm.io/installation) package manager
* [Git CLI](https://git-scm.com/)

For following along in the code in future lessons, it's also helpful to make sure you have a code editor, like [VS Code](https://code.visualstudio.com/), to open your Makeswift project once installed.

> **Info**
>
> [Node Version Manager](https://github.com/nvm-sh/nvm) (nvm) is an alternative way to install Node.js and allows you to install and use different versions.
>
> With nvm installed, you can install a specific version:
>
> *nvm install 22*
>
> ... and switch to the Node.js runtime of any version you have installed:
>
> *nvm use 22*
>
> Whether you use nvm or install Node.js via another method, make sure you are running a compatible version:
>
> *node -v*

## 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.

![A Catalyst deployment in progress](/_fern-img/aa0fbe759dd36f1662e29a01000bb56bba5c0310adf842a8e30afba0b78f93e7.webp)

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.

> **Info**
>
> Note that you can return to the storefront overview page at any time by navigating to Channel Manager (or Channels) in your control panel and clicking on the Catalyst storefront channel.

## 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*.

```shell showLineNumbers={false}
npm install -g degit
```

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

```shell showLineNumbers={false}
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.

```shell showLineNumbers={false}
cd /path/to/working/directory
git init
git add .
git commit -m "Initial project files"
```

4. **Install** the project dependencies.

```shell showLineNumbers={false}
corepack enable pnpm && pnpm install
```

> **Info**
>
> ### Troubleshooting
>
> *The pnpm command is unrecognized.*
>
> In some environments where file permissions are highly restricted, you may need to prepend *corepack* to the use of *pnpm* commands (for example, *corepack pnpm install*)

5. **Run** the following command.

```shell showLineNumbers={false}
pnpm catalyst channels 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.

```text showLineNumbers={false}
cd /path/to/catalyst/project
```

2. **Run** the dev server.

```text showLineNumbers={false}
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.

![Example of a fresh local site](/_fern-img/444693394cbf8981d40e48f553880c85c6e733369a36e5fd68b1bb3ff5a956f4.webp)

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.

> **Info**
>
> ### Troubleshooting
>
> If you encounter an error while starting the dev server related to an issue finding a matching *keyid*, you may need to upgrade a pre-existing \_corepack\_version.
>
> *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.

| Variable                                        | Description                                                                                                                                                                                                                             |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AUTH\_SECRET                                    | A secret value used for Auth.js authenticated session management                                                                                                                                                                        |
| CATALYST\_ACCESS\_TOKEN                         | A BigCommerce REST API token generated during the device auth flow, used exclusively by the Catalyst CLI (for example, to authorize commands like *channel link*)                                                                       |
| BIGCOMMERCE\_STORE\_HASH                        | The hash of the BigCommerce store this project is connected to                                                                                                                                                                          |
| BIGCOMMERCE\_CHANNEL\_ID                        | The ID of the new storefront channel that was created in your store. This new channel has the type "storefront" and the platform "catalyst".                                                                                            |
| BIGCOMMERCE\_STOREFRONT\_TOKEN                  | The private [GraphQL Storefront API token](/developer/api-reference/rest/admin/authentication-apis/storefront-api-tokens/private-api-token/create-private-token) that Catalyst uses for its interactions with the BigCommerce platform. |
| BIGCOMMERCE\_STOREFRONT\_UNAUTHENTICATED\_TOKEN | A private Storefront API token limited to the "Unauthenticated" scope, used to proxy client-side GraphQL requests.                                                                                                                      |
| ENABLE\_ADMIN\_ROUTE                            | Enables the convenience URL path */admin* on the storefront, which will direct you to your store's control panel                                                                                                                        |
| TURBO\_REMOTE\_CACHE\_SIGNATURE\_KEY            | Used only by older monorepo-structure projects that build with Turborepo. You can leave it unset.                                                                                                                                       |
| MAKESWIFT\_SITE\_API\_KEY                       | The API key of the Makeswift dev site                                                                                                                                                                                                   |

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.

> **Info**
>
> CATALYST\_ACCESS\_TOKEN is separate from the optional BIGCOMMERCE\_ACCESS\_TOKEN variable. BIGCOMMERCE\_ACCESS\_TOKEN can be scoped independently of the CLI's own authorization, and is used by the storefront application at runtime for certain features that require REST API access.

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 cache. Below is an example set of steps to do both.

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. **Start** the dev server again.

```text showLineNumbers={false}
pnpm run dev
```

> **Info**
>
> Make sure only to clear the cache when necessary. Clearing it means the next build starts from scratch, which takes longer.