Native Hosting Overview

BigCommerce provides hosting for your Catalyst projects, allowing you to fully deploy your Catalyst storefront without having to depend on an external hosting provider.

To get started using the Catalyst CLI to deploy your Catalyst project, refer to the Getting Started docs.

Core Concepts

To understand BigCommerce’s Native Hosting for Catalyst, here are a few concepts you need to know.

Project

A project is the top-level infrastructure container for your application. You create a project once, then use it as the target for future deployments of that storefront.

Deployment

A deployment is a specific version of your project that has been built and released. Each deployment reflects the state of the code at a point in time (when it was built and successfully deployed).

OpenNext

OpenNext is an open source project that strives to support Next.js being hosted across different platforms while maintaining feature parity with Vercel. OpenNext provides adapters for deploying to different hosting providers like Cloudflare, Netlify, AWS, etc. For deploying to BigCommerce’s hosting infrastructure, you will need to install the OpenNext Cloudflare adapter in your repository as defined in the Installation section below.

See the OpenNext Cloudflare documentation for more details.

Authentication

The Catalyst CLI supports two ways to authenticate, depending on where it’s running:

• Interactive (local development) — Run catalyst auth login to authenticate via your browser using OAuth. After logging in, your store hash and access token are stored locally in .bigcommerce/project.json for use by other CLI commands. Use catalyst auth logout to remove stored credentials, and catalyst auth whoami to verify your current session.
• Non-interactive (CI/CD) — In environments like GitHub Actions or CircleCI where a browser is not available, provide your store hash and access token directly via CLI flags (--store-hash, --access-token), environment variables (CATALYST_STORE_HASH, CATALYST_ACCESS_TOKEN), or an env file. See the Configuration section below for the full priority order.

See the CLI Reference for full details on the auth commands.

Configuration

The Catalyst CLI depends on several configuration variables:

• CATALYST_STORE_HASH - the hash of your Catalyst store. Falls back to BIGCOMMERCE_STORE_HASH if unset.
• CATALYST_PROJECT_UUID - the unique identifier for the BigCommerce infrastructure project
• CATALYST_ACCESS_TOKEN - the Access Token that has modify permissions on Infrastructure Projects and Infrastructure Deployments as well as read-only permissions on Infrastructure Logs
• CATALYST_TELEMETRY_DISABLED - whether or not telemetry is disabled

When looking for configuration variables, the Catalyst CLI will search in the following places, in order of priority (highest first):

Individual parameter flags — Manually pass individual configuration parameters in the CLI command. For example:

$
catalyst deploy --store-hash <CATALYST_STORE_HASH> --access-token <CATALYST_ACCESS_TOKEN>

Environment variable file flag — Pass the path to an environment file to load variables from. The path is resolved relative to the current working directory. For example:

$
catalyst deploy --env-path .env.prod

process.env — Environment variables you have already set. They may be applied through your hosting platform, a UI, and so on (for example, setting secret credentials in GitHub Actions).

.env.local — Automatically loaded from the current working directory if present.

.bigcommerce/project.json — The local configuration file that is generated after creating or linking a project. It includes your store hash, project uuid, access token, and any variables saved with catalyst env add.

project.json Configuration File

The configuration for the BigCommerce infrastructure project that your repository is connected to is defined in the .bigcommerce/project.json file. The configuration file is generated when running the link command to create a new project or connect to an existing one.

1
{
2
  "framework": "catalyst",
3
  "projectUuid": "<PROJECT-UUID>",
4
  "accessToken": "<ACCESS_TOKEN>",
5
  "storeHash": "<STORE_HASH>",
6
  "env": {
7
    "BIGCOMMERCE_STOREFRONT_TOKEN": "<STOREFRONT_TOKEN>"
8
  }
9
}

The configuration file contains the following properties:

• projectUuid - the unique identifier of the connected BigCommerce project
• storeHash - the hash of the BigCommerce store associated with the accessToken
• framework - the framework to target when building. Always catalyst.
• accessToken - the Access Token that has modify permissions on Infrastructure Projects and Infrastructure Deployments as well as read-only permissions on Infrastructure Logs
• env - deployment environment variables saved with catalyst env add. Sent as encrypted secrets on every catalyst deploy.

As described above, the values in the project.json file have the lowest priority and will be used if none of the other options have been used.

You can remove the .bigcommerce/ folder to reset your project’s configuration, but this action will require re-running the pnpm catalyst create or pnpm catalyst link command to re-connect to your project.