DocsStorefrontCatalystDeploymentNative Hosting

Getting Started

Beta

The Catalyst CLI is generally available, but Native Hosting is currently in closed beta. There may be breaking changes to the Native Hosting APIs as we finalize them. To express interest in gaining access, fill out the Native Hosting Closed Beta Interest Form.

This guide shows how to deploy a Catalyst application to BigCommerce’s Native Hosting infrastructure with the Catalyst CLI. If you’re starting from scratch, follow the New project quick start. If you already have a Catalyst repository, jump to Set up with an existing project. Both paths converge on the shared Working with your deployment steps.

Make sure to read the Overview documentation for how BigCommerce’s hosting infrastructure and configuration variables work, and the CLI Reference for the full list of commands.

Prerequisites

  1. 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 beta, you must be approved to have this flag turned on.
  2. Configuration variables - Refer to the Overview documentation for which variables are needed and where they are read from.
  3. Your store user account must have “high-risk user permissions” to create Store-level API Accounts.

Scaffold, deploy, and view a hosted storefront in five steps.

  1. Scaffold a project. The CLI walks you through naming the project, authenticating via your browser, and connecting a channel, then writes your credentials to .env.local, installs dependencies, and initializes a git repository.

    $pnpm create @bigcommerce/catalyst@latest

    To set up Native Hosting at the same time, add the --hosting commerce flag. When you omit it, scaffolding stays hosting-agnostic and you can opt in later — the first catalyst deploy will offer to run setup for you.

    $pnpm create @bigcommerce/catalyst@latest --hosting commerce

  2. Run it locally. This starts the dev server and generates the GraphQL types the build needs.

    $cd <your-project>
    $pnpm dev

  3. Create your Native Hosting project. This creates a BigCommerce infrastructure project and links it to your local repository.

    $pnpm catalyst project create

  4. Deploy. The CLI builds your project and deploys the assets to BigCommerce’s hosting infrastructure. On success it prints a View your deployment at: URL — that line is the success signal.

    $pnpm catalyst deploy

  5. View your storefront at the printed deployment URL.

Because you authenticated during step 1, you can skip the Authenticate step. To add runtime secrets, point a channel at the deployment, or attach a custom domain, continue with Working with your deployment.

Set up with an existing project

If you already have a Catalyst project (created via the One-Click Catalyst app or manually), add Native Hosting to it.

  1. Install the CLI and the OpenNext Cloudflare adapter in the directory that contains your Catalyst app (the project root for a standalone project, or core/ in the monorepo template).

    $pnpm add @bigcommerce/catalyst@latest @opennextjs/cloudflare@latest

  2. Authenticate. See Authenticate below.

  3. Create or link a project. See Create or link a project below.

  4. Deploy. The first time you run pnpm catalyst deploy (or pnpm catalyst project link) on a project that isn’t set up yet, the CLI prompts to run Commerce Hosting setup. Accepting it transforms your project automatically so you don’t have to make these changes by hand:

    • Renames proxy.ts to middleware.ts, changes export const proxy to export const middleware, and adds runtime: 'experimental-edge' to the exported config. This is required because proxy.ts is locked to the Node.js runtime, which the OpenNext Cloudflare adapter doesn’t support. (This workaround will be removed once the adapter supports Node middleware via the Adapters API.)
    • Installs @opennextjs/cloudflare.
    • Detects the default instrumentation.ts (which registers @vercel/otel, incompatible with the Cloudflare Workers bundle and the cause of a “Failed to prepare server” error at cold start) and prompts to remove it and drop @vercel/otel from package.json.

    The instrumentation.ts removal prompt only appears in an interactive terminal. In any non-interactive context (CI, piped input, or a background shell), the cleanup is silently skipped — delete or gate instrumentation.ts yourself, or your deployed worker will keep logging the cold-start error.

Once setup completes, continue with Working with your deployment.

Working with your deployment

The steps below apply to both paths above once your project is set up. See the CLI Reference for the full list of commands and options.

Authenticate

Commands that interact with the BigCommerce API need your store credentials.

If you scaffolded your project with pnpm create, you’re already authenticated — the CLI stored your credentials in .env.local during setup, so you can skip this step.

Otherwise — for example, a freshly cloned repository with no stored credentials — authenticate based on your environment:

Local development (interactive): Run pnpm catalyst auth login to authenticate via your browser. The CLI opens the BigCommerce authorization page, walks you through an OAuth device-code flow, and stores 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 reads them 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.

Run the project create command to create a new BigCommerce infrastructure project and link it to your local repository.

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

Runtime environment variables and secrets

In addition to the configuration variables mentioned in the creation step, your deployment needs the runtime variables that Catalyst requires. See the Environment Variables documentation for a full list of required variables.

Save those runtime variables once with catalyst env add. They are stored in .bigcommerce/project.json and sent as encrypted secrets on every deploy, so you don’t need to pass them again each time.

$pnpm catalyst env add BIGCOMMERCE_STORE_HASH=<YOUR_STORE_HASH> BIGCOMMERCE_STOREFRONT_TOKEN=<YOUR_STOREFRONT_TOKEN>

To set or override a variable for a single deployment without storing it, pass it with the --secret flag. A --secret value takes precedence over a stored value for the same key.

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

Running pnpm catalyst deploy invokes the CLI directly and does not run the GraphQL codegen step. On a brand-new project this can surface a TypeScript error such as 'response.data' is of type 'unknown' because the generated types don’t exist yet. Run pnpm dev once (or pnpm build, or pnpm run generate) to generate them before deploying. In CI, use pnpm run deploy, which runs codegen first.

After a successful deploy, the CLI prints output similar to the following. The final View your deployment at: line is the success signal — if it’s missing, the deploy failed even when the surrounding build output looks normal.

◢ @bigcommerce/catalyst v1.0.0
◐ Copying templates...
✅ Templates copied
◐ Building project...
┌─────────────────────────────┐
│ OpenNext — Cloudflare build │
└─────────────────────────────┘
App directory: ~/path/to/your-project
Next.js version : 16.2.10
@opennextjs/cloudflare version: 1.17.3
@opennextjs/aws version: 3.9.16
# ... Next.js compilation and static page generation ...
✓ Compiled successfully in 6.2s
✓ Generating static pages using 9 workers (24/24) in 632.5ms
# ... route summary and OpenNext bundling ...
OpenNext build complete.
 ⛅️ wrangler 4.90.0
Total Upload: 17776.22 KiB / gzip: 3721.89 KiB
✅ Project built
ℹ️ Generating bundle...
✅ Bundle created at: ~/path/to/your-project/.bigcommerce/bundle.zip
ℹ️ Generating upload signature...
✅ Upload signature generated.
ℹ️ Uploading bundle...
✅ Bundle uploaded successfully.
ℹ️ Creating deployment...
✅ Deployment started...
ℹ️ Fetching deployment status...
✅ Deployment completed successfully.
✅ View your deployment at: https://<your-project>.catalyst-sandbox.store

Point a channel at your deployment

After a successful deploy, point a BigCommerce channel’s site URL at one of your deployment hostnames so the storefront resolves to your new deployment. Run channel update to select a channel and hostname interactively.

$pnpm catalyst channel update

To skip the prompts, pass the channel and hostname directly. Run pnpm catalyst project list to see the available deployment hostnames.

$pnpm catalyst channel update --channel-id <CHANNEL_ID> --hostname <DEPLOYMENT_HOSTNAME>

You can also let the deploy do this for you by passing --update-site-url, which prompts to update a channel’s site URL after a successful deploy.

(Optional) Add a custom domain

By default, your deployment is served from a BigCommerce-provided hostname in the form <your-project>.catalyst-sandbox.store (your worker URL), shown in the catalyst deploy output and via pnpm catalyst project list. To serve it from your own domain, add the domain to your project with catalyst domains add and create the matching DNS record at your DNS provider.

Subdomain (e.g. shop.example.com) — create a CNAME record pointing at your worker URL.

Type:   CNAME
Host:   shop
Value:  <your-project>.catalyst-sandbox.store

Apex/root domain (e.g. example.com) — create an A record pointing at your store IP, which you can find in the store Control Panel under Settings → Email & DNS Records.

Type:   A
Host:   @
Value:  <your-store-ip>

Then register the domain with the CLI:

$pnpm catalyst domains add www.example.com

New domains start in a pending verification state and become active once DNS has propagated and BigCommerce can verify the record. DNS propagation can take anywhere from a few minutes up to a day, so check back on the status periodically rather than waiting on a single command. You can check a domain’s status at any time, list all domains on the project, and remove a domain you no longer need.

$# Check the status of a domain
$pnpm catalyst domains status www.example.com
$
$# List all custom domains on the project
$pnpm catalyst domains list
$
$# Remove a custom domain
$pnpm catalyst domains remove www.example.com

See the CLI Reference for the full set of domains options.

View logs

Once your storefront is deployed, you can stream live logs or query historical ones. Both commands are scoped to your linked project.

$# Stream live logs
$pnpm catalyst logs tail
$
$# Query historical logs (up to a 7-day window)
$pnpm catalyst logs query --since 1h --level-min error

The --format request option renders access-log style output that’s useful for spotting failing routes and status codes, and --format json is handy for piping into other tools. See the CLI Reference for the full set of logs filters.

Troubleshooting

SymptomWhat to try
deploy can’t find a projectRun pnpm catalyst project list, then pnpm catalyst project create or pnpm catalyst project link.
Auth / “unauthorized” errorsRun pnpm catalyst auth logout, then pnpm catalyst auth login to re-authenticate.
TypeScript error like 'response.data' is of type 'unknown' on a fresh projectGraphQL codegen hasn’t run yet. Run pnpm dev once (or pnpm build / pnpm run generate) before deploying; in CI, use pnpm run deploy.
Storefront won’t boot / “Failed to prepare server”Check pnpm catalyst logs tail on cold start. A leftover instrumentation.ts using @vercel/otel is the usual cause — remove or gate it (the auto-cleanup is skipped in non-interactive setups).
Missing runtime variables in productionPersist them with pnpm catalyst env add KEY=VALUE, or pass --secret KEY=VALUE for a single deploy.
Any crashIf telemetry is enabled, the CLI prints a Correlation ID — include it when you contact support so we can trace the run.