Catalyst is a composable, fully customizable headless storefront that offers a set of opinionated defaults. It is intended to fit the needs of modern developers, merchants, and shoppers. Catalyst is built with Next.js (nextjs.org) and uses our React.js-based (react.dev) Reactant storefront components.

The Catalyst monorepo contains the following:

• The core Catalyst Next.js storefront, in apps/core.
• An experimental version of Catalyst that uses the Makeswift (makeswift.com) low-code page builder, in apps/with-makeswift.
• The Reactant storefront component library, in packages/reactant.
• The BigCommerce GraphQL Storefront API (BigCommerce Dev Center) client, in packages/client.

• Node.js 18+
• Corepack-managed pnpm

Use Node.js 18+.

You may wish to use Node Version Manager, or nvm (GitHub), to facilitate moving back and forth between different versions of node. You can install nvm using either the instructions at the preceding link or your operating system package manager of choice.

This project uses corepack (nodejs.org) to install and enable the pnpm (pnpm.io) package manager. Corepack comes bundled with Node 18, so you do not need to install either of these packages on their own.

Catalyst is configured such that pnpm replaces npm. When you enhance your project with additional packages or scripts, be sure to use the pnpm command. For more information, see the pnpm documentation.

1. Clone the project to your local environment:

git clone [email protected]:bigcommerce/catalyst.git && cd catalyst

2. To help stay up to date with the latest changes, add the BigCommerce repo to your project as the upstream repository:

git remote add upstream [email protected]:bigcommerce/catalyst.git

3. Use corepack to enable pnpm, then use pnpm to install project dependencies:

corepack enable pnpm

pnpm install

4. Set up environment variables.

This repository contains a setup script that generates a local development environment file, .env.local. The environment file contains the authentication credentials and other variables required to connect Catalyst to an existing BigCommerce store. Run the script from the root directory of this repository and follow the prompts:

node scripts/setup.mjs

If you prefer to manually enter your own environment variables, you can run cp .env.example .env.local to get started.

The following table contains a description of each variable in the .env.local file:

5. Optionally, to optimize your workflow, use the following command to configure VSCode with the project-specific settings the Catalyst team has created:

cp .vscode/settings.example.json .vscode/settings.json

6. Start the Catalyst development server!

pnpm run dev

The dev script runs all packages and apps in watch mode. The following table lists localhost URLs with the default ports. When a port is unavailable, Catalyst uses the next available port. For example, if 3000 is in use, core and with-makeswift will run on 3001 and 3002, respectively.

Happy developing! Let us know how things are going in the dedicated Slack channel.

If you are able to install and use the Vercel CLI (vercel.com) on your local machine, you can use it to pull the environment variables from Vercel. The vercel CLI is not required to run Catalyst locally.

1. Link the app to your Vercel project

This command will take you through the process of linking the app to your Vercel project.

vercel link

2. Pull the environment variables from Vercel

This will pull the development environment variables from Vercel and write them to .env.local.

vercel env pull .env.local

If you need to pull the production environment variables for debugging, use the --prod flag.

vercel env pull .env.production --prod

One common way to deploy a Next.js app for development is to use the Vercel Platform (vercel.com). Consult the Next.js deployment documentation (next.js) for more details.

• Next.js documentation (nextjs.org)
• Interactive Next.js tutorial (nextjs.org)
• Next.js repository (GitHub)