> This page is for Developer. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.bigcommerce.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server. # Getting Started > Deploy a Catalyst storefront to BigCommerce Native Hosting with the Catalyst CLI, from a new project or an existing one. 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](#new-project-quick-start-recommended). If you already have a Catalyst repository, jump to [Set up with an existing project](#set-up-with-an-existing-project). Both paths converge on the shared [Manage your deployment](#manage-your-deployment) steps. > **Warning** > > 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](https://docs.google.com/forms/d/e/1FAIpQLSfDepq3qRtEtavb1wQvSvdK21pwr_kNsYQbH2B7JjWYyptUSA/viewform?usp=header). For how Native Hosting's projects and configuration variables work, see the [Native Hosting overview](/developer/docs/storefront/catalyst/deployment/native-hosting/overview). For every command and flag, see the [CLI reference](/developer/docs/storefront/catalyst/reference/cli). ## 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](https://support.bigcommerce.com/s/article/Store-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. ```shell 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. ```shell pnpm create @bigcommerce/catalyst@latest --hosting commerce ``` > **Info** > > This scaffolds `@bigcommerce/catalyst-core` (no Makeswift) by default. For a Makeswift-connected project, add `--gh-ref @bigcommerce/catalyst-makeswift@latest`. See [Makeswift](/developer/docs/storefront/catalyst/makeswift/overview). 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. ```shell cd 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`. ```shell 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. ```shell pnpm catalyst deploy ``` 5. **View your storefront** at the printed deployment URL. Because you authenticated during step 1, you can skip the [Authenticate](#authenticate) step. To add runtime secrets, point a channel at the deployment, or attach a custom domain, continue with [Manage your deployment](#manage-your-deployment). ## Set up with an existing project If you already have a Catalyst project (created via [One-Click Catalyst](/developer/docs/storefront/catalyst/getting-started/one-click-catalyst#run-locally) or [CLI Installation](/developer/docs/storefront/catalyst/getting-started/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. ```shell pnpm add -D @bigcommerce/catalyst@latest ``` 2. **Authenticate.** See [Authenticate](#authenticate) below. 3. **Create or link a project.** See [Create or link a project](#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`. > **Warning** > > 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). ## 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`. ```shell 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](/developer/docs/storefront/catalyst/deployment/native-hosting/overview#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. ```shell pnpm catalyst projects create ``` If you've already created a project, link to it with `projects link` and the project's UUID instead. ```shell pnpm catalyst projects link --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](/developer/docs/storefront/catalyst/reference/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`](/developer/docs/storefront/catalyst/reference/environment-variables#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](/developer/docs/storefront/catalyst/deployment/native-hosting/github-actions). ```shell pnpm catalyst env add BIGCOMMERCE_STORE_HASH= BIGCOMMERCE_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. ```shell pnpm catalyst deploy --secret BIGCOMMERCE_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. ```text ◢ @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://.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. ```shell 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. ```shell pnpm catalyst channels update --channel-id --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. > **Warning** > > Changing a channel's site URL removes its custom checkout URL, so checkout falls back to the default channel's domain. After pointing a channel at a new hostname, set its checkout URL again. See [Checkout Domains](/developer/docs/storefront/catalyst/deployment/native-hosting/checkout-domains). ### (Optional) Add a custom domain By default, your deployment is served from a BigCommerce-provided hostname in the form `.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. ```shell pnpm catalyst domains add example.com ``` See [Custom Domains](/developer/docs/storefront/catalyst/deployment/native-hosting/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](/developer/docs/storefront/catalyst/deployment/native-hosting/makeswift). ## View logs Once your storefront is deployed, you can stream live logs or query historical ones. Both commands are scoped to your linked project. ```shell # 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`](/developer/docs/storefront/catalyst/reference/cli#logs-query) in the CLI reference for the full set of filters. ## Troubleshooting | Symptom | What to try | | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`deploy` can't find a project** | Run `pnpm catalyst projects list`, then `pnpm catalyst projects create` or `pnpm catalyst projects link`. | | **Auth / "unauthorized" errors** | Run `pnpm catalyst auth logout`, then `pnpm catalyst auth login` to re-authenticate. | | **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 production** | For local deploys, persist them with `pnpm catalyst env add KEY=VALUE`, or pass `--secret KEY=VALUE` for a single deploy. In CI, always pass `--secret`: `env add` stores values in `.bigcommerce/project.json`, which isn't committed. | | **Any crash** | If telemetry is enabled, the CLI prints a **Correlation ID** — include it when you contact support so we can trace the run. |