Getting Started

Below, you’ll find the steps for using the Catalyst CLI to deploy your Catalyst application. Make sure to read the Overview documentation for an overview of BigCommerce’s hosting infrastructure, how configuration variables work, etc.

Prerequisites

1. Local Catalyst repository - This can be created either via the One-Click Catalyst app or manually.
2. The Native Hosting feature flag enabled - This flag enables the core hosting APIs and allows you to create an API Account with the correct permissions. While Native Hosting is in closed Alpha, you must be approved to have this flag turned on.
3. Configuration variables - Refer to the Overview documentation for which variables are needed and where they are read from
4. Your store user account must have “high-risk user permissions” to create Store-level API Accounts.

Installation

Install the Catalyst CLI and the OpenNext Cloudflare adapter in the core directory of your Catalyst project.

$
cd core
$
pnpm add @bigcommerce/catalyst@alpha @opennextjs/cloudflare@1.17.3

In the scripts section of your core/package.json file, replace next build with catalyst build in the build script. Then, add a new script for deploying: "deploy": "catalyst deploy". The dev and start scripts remain unchanged and continue to use next dev and next start directly.

The final result will look like this.

1
{
2
  "build": "npm run generate && catalyst build",
3
  "deploy": "catalyst deploy"
4
}

For running Catalyst locally, you will still use the same terminal command you used in the past, pnpm dev.

Next.js 16 Migration Note

1. Rename proxy.ts to middleware.ts
2. Change the export from export const proxy to export const middleware
3. Add the edge runtime to your exported config object:

1
export const config = {
2
  runtime: 'experimental-edge',
3
  matcher: [
4
    // ...your existing matchers
5
  ],
6
};

This is required because proxy.ts is locked to the Node.js runtime, which is not supported by the OpenNext Cloudflare adapter. Using middleware.ts with runtime: 'experimental-edge' ensures your middleware runs on Cloudflare Workers. This workaround will be removed once the OpenNext Cloudflare adapter adds support for Node middleware via the Adapters API.

Usage

The Catalyst CLI provides several commands for deploying a Catalyst storefront application to BigCommerce’s infrastructure. See the CLI Reference for a full list of commands and details.

Authenticate

Before running any commands that interact with the BigCommerce API, you need to provide your store credentials. How you do this depends on your environment:

Local development (interactive): Run pnpm catalyst auth login to authenticate via your browser. The CLI will walk you through an OAuth flow and store your credentials locally in .bigcommerce/project.json.

$
pnpm catalyst auth login

After logging in, you can omit the --store-hash and --access-token flags from all subsequent commands — the CLI will read them from project.json automatically.

CI/CD (non-interactive) — In environments like GitHub Actions where a browser is not available, provide credentials via environment variables (CATALYST_STORE_HASH, CATALYST_ACCESS_TOKEN) or pass them directly as flags (--store-hash and --access-token) on each command. See the Overview documentation for the full configuration priority order.

Create a project

Run the project create command to create a new BigCommerce infrastructure project.

$
pnpm catalyst project create

Alternatively, if you’ve already created a project, you can link to an existing one if you know the project’s uuid using the project link command.

$
pnpm catalyst project link --project-uuid <PROJECT_UUID>

After creating a new project or linking to an existing one, a .bigcommerce/project.json file should have been created for you. This file will store the necessary configuration variables such as your store hash, access token, etc. Since this file includes an access token, it should not be checked into source control.

Deploy your Catalyst project

When you’re ready, run the deploy command to build your Catalyst project and deploy those build assets to BigCommerce’s hosting infrastructure.

In addition to the deploy command depending on the configuration variables mentioned in the creation step, you’ll also need to include the runtime variables necessary for Catalyst. See the Environment Variables documentation for a full list of required variables.

You’ll need to pass each of your runtime variables into the deploy command as a secret by using the --secret flag. The --secret flag ensures that each of your variables is encrypted and is not human readable after creation.

For example, to pass the BIGCOMMERCE_STORE_HASH and BIGCOMMERCE_STOREFRONT_TOKEN variables, the command would look like this:

$
pnpm catalyst deploy --secret BIGCOMMERCE_STORE_HASH=<YOUR_STORE_HASH> --secret BIGCOMMERCE_STOREFRONT_TOKEN=<YOUR_STOREFRONT_TOKEN>

Again, make sure to pass all necessary runtime variables.