Vercel and BigCommerce Integration

BigCommerce is an ecommerce platform for building and managing online storefronts. This guide explains how to deploy a highly performant, 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 either deploy the template below to Vercel or use the following steps to fork and clone it to your machine and deploy it locally.

Catalyst by BigCommerce

Developer-first ecommerce: customizable UI kit, comprehensive GraphQL API client, optimized for Next.js & React Server Components.

1. Set up a BigCommerce account and storefront

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

   • Start a free trial
   • Create a developer sandbox

2. Fork and clone the Catalyst repository

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

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

   Replace <YOUR_GITHUB_USERNAME> with your GitHub username and <YOUR_FORK_NAME> with the name you chose for your fork.

3. Add the upstream Catalyst repository

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

   Terminal

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

   Verify the local repository is set up with the remote repositories using the following command:

   Terminal

   git remote -v

   The output should look similar to this:

   Terminal

   origin    [email protected]:<YOUR_GITHUB_USERNAME><YOUR_FORK_NAME>.git (fetch)
   origin    [email protected]:<YOUR_GITHUB_USERNAME>/<YOUR_FORK_NAME>.git (push)
   upstream  [email protected]:bigcommerce/catalyst.git (fetch)
   upstream  [email protected]:bigcommerce/catalyst.git (push)

   Learn more about syncing a fork.

4. Enable Corepack and install dependencies

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

   Terminal

   corepack enable pnpm && pnpm install

5. Run the Catalyst CLI command

   The Catalyst CLI (Command Line Interface) is a tool that helps set up and configure your Catalyst 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

   To start this process, run the following command:

   Terminal

   pnpm create @bigcommerce/catalyst@latest init

   Follow the CLI prompts to complete the setup.

6. Start the development server

   After setting up your Catalyst project and configuring the environment variables, you can start the development server. From your project root, run the following command:

   Terminal

   pnpm dev

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

Deploy to Vercel

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

1. Create a new Vercel project

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

2. Link your Vercel project

   To ensure seamless management of deployments and project settings you can link your local development environment with your Vercel project.

   If you haven't already, install the Vercel CLI globally with the following command:

   Terminal

   pnpm i -g vercel

   This command will prompt you to log in to your Vercel account and link your local project to your existing Vercel project:

   Terminal

   vercel link

   Learn more about the Vercel CLI.

Enable Vercel Remote Cache

Vercel Remote Cache optimizes your build process by sharing build outputs across your Vercel team, eliminating redundant tasks. Follow these steps to set up Remote Cache:

1. Authenticate with Turborepo

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

   Terminal

   npx turbo login

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

   Terminal

   npx turbo login --sso-team=team-slug

2. Link your Remote Cache

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

   Terminal

   turbo link

   If you run these commands but the owner has disabled Remote Caching for your team, Turborepo will present you with an error message: "Please contact your account owner to enable Remote Caching on Vercel."

3. Add Remote Cache Signature Key

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

   Terminal

   vercel env add TURBO_REMOTE_CACHE_SIGNATURE_KEY

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

   Once finished, pull the new environment variable into your local project with the following command:

   Terminal

   vercel env pull

   Learn more about Vercel Remote Cache.

Enable Web Analytics and Speed Insights

The Catalyst monorepo comes pre-configured with Vercel Web Analytics and Speed Insights, offering you powerful tools to understand and optimize your storefront's performance. To learn more about how they can benefit your ecommerce project, visit our documentation on Web Analytics and Speed Insights.

Web Analytics provides real-time insights into your site's traffic and user behavior, helping you make data-driven decisions to improve your storefront's performance:

Open Web Analytics

Speed Insights offers detailed performance metrics and suggestions to optimize your site's loading speed and overall user experience:

Open Speed Insights

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