> 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 a Catalyst Project Plan: Composable Developer Lesson 5 of 19 · 30 min ## 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](/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 Catalyst project once installed. > **Info** > > If you run into an error related to your maximum number of active storefronts during the Catalyst CLI installation, this means you do not have sufficient storefront seats. > > In Channel Manager (or Channels) in your store control panel, you will need to either delete/deactivate a channel, "Add new" and confirm/update all requirements for multi-storefront if you haven't previously done so, or else use a different sandbox store with an available seat. > **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 24` > > ... and switch to the Node.js runtime of any version you have installed: > > `nvm use 24` > > 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. > **Info** > > Make sure to follow the instructions below to set up. Do not run the typical create @bigcommerce/catalyst command! 1. **Install** `degit`. ```bash showLineNumbers={false} npm install -g degit ``` 2. **Run** the following command, replacing the path to the working directory with your own path. ```bash showLineNumbers={false} degit https://github.com/bigcommerce-edu/lab-catalyst-makeswift-faqs#e-catalyst-start /path/to/working/directory ``` 3. **Navigate** to the new project working directory and **initialize** a Git repository for your project. ```bash showLineNumbers={false} cd /path/to/working/directory git init git add . git commit -m "Initial project files" ``` 4. **Install** the project dependencies. ```bash 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. ```bash 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. ```bash showLineNumbers={false} cd /path/to/catalyst/project ``` 2. **Run** the dev server. ```bash 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. > > ```bash showLineNumbers={false} > 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. ## 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](https://support.bigcommerce.com/s/article/Shipping-Zones) that applies to any billing address you will use at checkout * An enabled [Shipping Method](https://support.bigcommerce.com/s/article/Shipping-Methods) 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 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. ```bash 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.