Getting Started

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 Manage your deployment steps.

For how Native Hosting’s projects and configuration variables work, see the Native Hosting overview. For every command and flag, see the CLI reference.

Prerequisites

• Native Hosting access. The Native Hosting feature flag enables the hosting APIs and lets you create an API account with the right permissions. While Native Hosting is in closed beta, you must be approved to have it turned on.
• Permission to create API accounts. Your store user account needs the high-risk user permissions to create store-level API accounts.

New project quick start (recommended)

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 storefront variables to .env.local and your CLI credentials to .bigcommerce/project.json, 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
   This scaffolds @bigcommerce/catalyst-core (no Makeswift) by default. For a Makeswift-connected project, add --gh-ref @bigcommerce/catalyst-makeswift@latest. See Makeswift.

2. Run it locally (optional). Start the dev server to check your storefront before deploying. catalyst deploy generates the GraphQL types it needs on its own, so this step isn’t required.

   cd <your-project>
   pnpm dev

3. Create your Native Hosting project. Skip this step if you scaffolded with --hosting commerce — that flag already created or selected a hosting project and linked it, and running projects create again would create a second project and replace the link.

   Otherwise, run this from your project root. It creates a project in BigCommerce’s hosting infrastructure — not a local file — and links your local repository to it by writing .bigcommerce/project.json.

   pnpm catalyst projects 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 Manage your deployment.

Set up with an existing project

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

1. Install the CLI in the directory that contains your Catalyst app (the project root for a standalone project, or core/ in a legacy monorepo-structure project). You don’t need to install the OpenNext Cloudflare adapter yourself: Commerce Hosting setup (step 4) adds it, pinned to the version the CLI supports.

   pnpm add -D @bigcommerce/catalyst@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 projects 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.)
   • Adds @opennextjs/cloudflare to package.json, pinned to the version the CLI supports.
   • 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 skipped with a warning — delete or gate instrumentation.ts yourself, or your deployed worker will keep logging the cold-start error.

Once setup completes, continue with Manage your deployment.

Manage your deployment

The steps below apply to both paths above once your project is set up.

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 .bigcommerce/project.json 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 Configuration in the Native Hosting overview for the full priority order.

Create or link a project

Run the projects create command from your project root — the directory containing your Catalyst app. This creates a new project in BigCommerce’s hosting infrastructure and links your local repository to it.

pnpm catalyst projects create

If you’ve already created a project, link to it with projects link and the project’s UUID instead.

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

Creating or linking a project writes .bigcommerce/project.json, which stores your store hash, access token, and project UUID. Because this file includes an access token, don’t commit it to 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. If your store offers wallet payment methods (such as PayPal) on the cart page, also add BIGCOMMERCE_STOREFRONT_UNAUTHENTICATED_TOKEN, which those buttons need. The build doesn’t check for it, so a deploy without it succeeds but the buttons fail.

Save those runtime variables once with catalyst env add. They are stored in .bigcommerce/project.json and sent as encrypted secrets on every deploy from that machine, so you don’t need to pass them again each time. Because .bigcommerce/ isn’t committed to source control, stored values aren’t available in CI; pass them with --secret there instead. See GitHub Actions.

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>

catalyst deploy generates your project’s GraphQL types before it builds, so a fresh project doesn’t need a separate pnpm dev or pnpm build 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.4.2
◐ Generating GraphQL types...
✅ GraphQL types generated
◐ Copying templates...
✅ Templates copied
◐ Building project...
# ... OpenNext Cloudflare build, Next.js compilation, and Wrangler bundling ...
✅ 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 channels update to select a channel and hostname interactively.

pnpm catalyst channels update

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

pnpm catalyst channels 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 projects 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.

pnpm catalyst domains add example.com

See Custom Domains for the full setup, including DNS records, verification, and managing domains across projects.

(Makeswift projects) Set the production API key

If your project is Makeswift-connected, pointing a channel at your deployment also updates the connected Makeswift site’s base URL, so you don’t need to change it in Makeswift. The CLI doesn’t change MAKESWIFT_SITE_API_KEY, though, so your deployment keeps the key from .env.local, which is usually your development site’s. To set your production site’s key, see Makeswift on Native Hosting.

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 logs query in the CLI reference for the full set of filters.

Troubleshooting