Deploy a headless BigCommerce storefront with Vercel

BigCommerce is an ecommerce platform for building and managing online storefronts. This guide explains how to deploy a headless storefront using Next.js on Vercel.

This guide uses Catalyst by BigCommerce to connect your BigCommerce store to a Vercel deployment. Catalyst was developed by BigCommerce in collaboration with Vercel.

You can deploy the Catalyst by BigCommerce template directly to Vercel, or use the steps below to fork and clone it locally.

You can use an existing BigCommerce account and storefront, or get started with one of these options:

• Start a free trial
• Create a developer sandbox

1. Fork the Catalyst repository on GitHub. You can name your fork as you prefer. This guide refers to it as <YOUR_FORK_NAME>.
2. Clone your forked repository to your local machine:

git clone <https://github.com/><YOUR_GITHUB_USERNAME>/<YOUR_FORK_NAME>.git
cd <YOUR_FORK_NAME>

To automatically sync updates, add the BigCommerce Catalyst repository as a remote named "upstream":

git remote add upstream git@github.com:bigcommerce/catalyst.git

Verify the local repository is set up with the remote repositories:

git remote -v

The output should look similar to this:

origin    git@github.com:<YOUR_GITHUB_USERNAME>/<YOUR_FORK_NAME>.git (fetch)
origin    git@github.com:<YOUR_GITHUB_USERNAME>/<YOUR_FORK_NAME>.git (push)
upstream  git@github.com:bigcommerce/catalyst.git (fetch)
upstream  git@github.com:bigcommerce/catalyst.git (push)

Learn more about syncing a fork.

Catalyst requires pnpm as the Node.js package manager. Corepack helps manage package manager versions. Run this command to enable Corepack, activate pnpm, and install dependencies:

corepack enable pnpm && pnpm install

The Catalyst CLI helps set up and configure your project. When run, it will:

1. Guide you through logging into your BigCommerce store
2. Help you create a new or select an existing Catalyst storefront Channel
3. Automatically create an .env.local file in your project root

Run the following command:

pnpm create @bigcommerce/catalyst@latest init

Follow the CLI prompts to complete the setup.

After setting up your project and configuring the environment variables, start the development server from your project root:

pnpm dev

Your local storefront should now be accessible at http://localhost:3000.

Now that your Catalyst storefront is configured, deploy your project to Vercel.

Visit https://vercel.com/new to create a new project. You may be prompted to sign in or create a new account.

1. Find your forked repository in the list.
2. Click the Import button next to your repository.
3. In the Root Directory section, click the Edit button.
4. Select the core directory from the file tree. Click Continue to confirm your selection.
5. Verify that the Framework preset is set to Next.js. If it isn't, select it from the dropdown menu.
6. Open the Environment Variables dropdown and paste the contents of your .env.local into the form.
7. Click the Deploy button to start the deployment process.

To link your local development environment with your Vercel project, install the Vercel CLI globally:

pnpm i -g vercel

Then link your local project to your Vercel project:

vercel link

Learn more about the Vercel CLI.

Vercel Remote Cache optimizes your build process by sharing build outputs across your team, eliminating redundant tasks.

Run this command to authenticate the Turborepo CLI with your Vercel account:

pnpm dlx turbo login

For SSO-enabled Vercel teams, include your team slug:

pnpm dlx turbo login --sso-team=team-slug

To link your project to a team scope and specify who the cache should be shared with:

pnpm dlx turbo link

To securely sign artifacts before uploading them to the Remote Cache, add the TURBO_REMOTE_CACHE_SIGNATURE_KEY environment variable to your Vercel project:

vercel env add TURBO_REMOTE_CACHE_SIGNATURE_KEY

When prompted, add the environment variable to Production, Preview, and Development environments. Set the value to a secure random string by running openssl rand -hex 32 in your terminal.

Pull the new environment variable into your local project:

vercel env pull

Learn more about Vercel Remote Cache.

The Catalyst monorepo comes pre-configured with Vercel Web Analytics and Speed Insights. These tools help you understand and optimize your storefront's performance.

• Web Analytics provides real-time insights into your site's traffic and user behavior.
• Speed Insights offers detailed performance metrics and suggestions to optimize your site's loading speed.

For more advanced configurations, refer to the BigCommerce Catalyst documentation.