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

# Environment Variables

> Reference for the environment variables a Catalyst storefront reads, with their types, defaults, and whether the Catalyst CLI sets them.

This reference lists the environment variables a Catalyst storefront reads, with each variable's type, default, and when you need to set it.

## Required

Catalyst storefronts require the following variables to function.

> **Info**
>
> Required variables are CLI-configured: If you created your Catalyst storefront using the CLI and chose to connect to an existing store, the CLI configured these variables and added them to `.env.local`.

### BIGCOMMERCE_STORE_HASH

| Attribute            | Value  |
| :------------------- | :----- |
| Type                 | string |
| Permanently required | true   |
| CLI-configurable     | true   |

The store hash identifies the BigCommerce store connected to this Catalyst storefront.

You can find the store hash in the control panel URL, which takes the following form:

```shell showLineNumbers={false}
https://store-{BIGCOMMERCE_STORE_HASH}.mybigcommerce.com/manage
```

The store hash is also part of each channel's canonical URL, which adds the channel ID:

```shell showLineNumbers={false}
https://store-{BIGCOMMERCE_STORE_HASH}-{channelId}.mybigcommerce.com
```

The control panel URL doesn't include `{channelId}`. However, you should always include `{channelId}` in any references to your canonical URL in the Catalyst environment. This ensures that your requests are using the [correct channel context](/developer/docs/storefront/guides/graphql-storefront-api).

### BIGCOMMERCE_STOREFRONT_TOKEN

> **Warning**
>
> This token is a **sensitive secret**. Do not expose outside environment variables.

| Attribute            | Value  |
| :------------------- | :----- |
| Type                 | string |
| Permanently required | true   |
| CLI-configurable     | true   |

This is a GraphQL Storefront API **private** bearer token that authorizes server-to-server access to the [GraphQL Storefront API](/developer/docs/storefront/guides/graphql-storefront-api). It is used to query storefront data and generate the customer access token for requesting information specific to individual customers, such as getting wishlist items.

The private token must be created with the following access scopes:

| Scope             | Purpose                                                                                    |
| :---------------- | :----------------------------------------------------------------------------------------- |
| `Unauthenticated` | Query information from the perspective of an anonymous shopper.                            |
| `Customer`        | Access customer-specific data, such as product pricing, availability, and account details. |

**Without the CLI**

Create a store-level or app-level API account with the following token creation scope. Then use the API account access token to [Create a private token](/developer/api-reference/rest/admin/authentication-apis/storefront-api-tokens/private-api-token/create-private-token).

| UI Name               | Permission | Parameter              |
| :-------------------- | :--------- | :--------------------- |
| Storefront API Tokens | modify     | `store_storefront_api` |

### BIGCOMMERCE_CHANNEL_ID

| Attribute            | Value   |
| :------------------- | :------ |
| Type                 | integer |
| Permanently required | true    |
| CLI-configurable     | true    |

This numeric channel ID specifies which [sales channel](/developer/api-reference/rest/admin/management/channels) is associated with your Catalyst storefront.

**Without the CLI**
We recommend that you create a new channel of type `storefront` and platform `catalyst`, although Catalyst will still function if you use an existing channel ID that references a channel that has a different storefront type.

The default Stencil storefront that comes with every BigCommerce store by default has a channel ID of `1`. We do not recommend using any Stencil channel for a transactional Catalyst storefront, as Stencil channels do not support many headless features.

### AUTH_SECRET

> **Warning**
>
> This token is a **sensitive secret**. Do not expose outside environment variables.

| Attribute            | Value               |
| :------------------- | :------------------ |
| Type                 | string, hexadecimal |
| Permanently required | true                |
| CLI-configurable     | true                |

Auth.js, formerly NextAuth, uses this pseudo-random hex string to sign session JWTs.

**Without the CLI**
To generate, open the terminal and run the following command. Then copy-paste the output into your environment variables file. Learn more about how generation works under the hood in the [OpenSSL docs](https://www.openssl.org/docs/manmaster/man1/openssl-rand.html).

```shell showLineNumbers={false}
openssl rand -hex 32
```

## Recommended

Catalyst runs without the following values, but the features that depend on them don't work until you set them. Each entry says when you need it.

### BIGCOMMERCE_STOREFRONT_UNAUTHENTICATED_TOKEN

> **Warning**
>
> This token is a **sensitive secret**. Do not expose outside environment variables.

| Attribute        | Value                                                                         |
| :--------------- | :---------------------------------------------------------------------------- |
| Type             | string                                                                        |
| Default          | no value                                                                      |
| Required         | false                                                                         |
| CLI-configurable | false                                                                         |
| Recommended      | If your store offers wallet payment methods (such as PayPal) on the cart page |

This is a GraphQL Storefront API **private** bearer token limited to the `Unauthenticated` scope. Catalyst's [GraphQL proxy](/developer/docs/storefront/catalyst/development/middleware#with-graphql-proxy) uses it to forward GraphQL requests that client-side libraries make through your storefront domain, such as [`checkout-sdk-js`](https://github.com/bigcommerce/checkout-sdk-js) requests for wallet buttons, without exposing a storefront token in the browser. For signed-in customers, the proxy also passes along the customer access token, so customer-specific data like customer group pricing still resolves.

Use a separate token from [`BIGCOMMERCE_STOREFRONT_TOKEN`](#bigcommerce_storefront_token), which also carries the `Customer` scope, so that requests arriving from the browser get only the most restricted access.

You need this token if your store offers wallet payment methods (such as PayPal) on the cart page: Catalyst renders those buttons only when wallets are configured for the cart, and they're the only part of Catalyst that uses the GraphQL proxy by default. You also need it if you allow other client-side libraries to use the proxy. If neither applies, you can leave it unset.

The Catalyst CLI doesn't create this token, so new projects start with it unset. Without it, requests through the GraphQL proxy are sent without a valid token and fail, but builds and deploys still succeed.

The private token must be created with the following access scope:

| Scope             | Purpose                                                         |
| :---------------- | :-------------------------------------------------------------- |
| `Unauthenticated` | Query information from the perspective of an anonymous shopper. |

To create it, use a store-level or app-level API account with the following token creation scope. Then use the API account access token to [Create a private token](/developer/api-reference/rest/admin/authentication-apis/storefront-api-tokens/private-api-token/create-private-token).

| UI Name               | Permission | Parameter              |
| :-------------------- | :--------- | :--------------------- |
| Storefront API Tokens | modify     | `store_storefront_api` |

The GraphQL proxy was added in [Catalyst 1.7.0](/developer/docs/storefront/catalyst/release-notes/1-7-0#client-side-graphql-proxy).

## Optional

The following values relate to Catalyst's tunable parameters, which may not be relevant to all users, hosting platforms, or scenarios. Consider which ones are right for your implementation and development phase.

### TURBO_REMOTE_CACHE_SIGNATURE_KEY

> **Warning**
>
> This token is a **sensitive secret**. Do not expose outside environment variables.

| Attribute        | Value               |
| :--------------- | :------------------ |
| Type             | string, hexadecimal |
| Default          | no value            |
| Required         | false               |
| CLI-configurable | false               |
| Recommended      | false               |

> **Note**
>
> This variable applies only to [legacy monorepo-structure projects](/developer/docs/storefront/catalyst/getting-started/upgrading#legacy-monorepo-structure-projects) that build with Turborepo. Projects created with the Catalyst CLI are a standalone Next.js application and don't use Turborepo, so they don't need it. It may still appear in your project's `.env.example`; you can leave it unset.

Providing a pseudo-random hex string for this environment variable lets you use the [Turborepo Remote Cache feature with signed artifacts](https://turbo.build/repo/docs/core-concepts/remote-caching#artifact-integrity-and-authenticity-verification), which will improve your build performance in Vercel and other environments that use Turborepo.

Do not re-use the value from `AUTH_SECRET`.

To generate, open the terminal and run the following command. Then copy-paste the output into your environment variables file. Learn more about how generation works under the hood in the [OpenSSL docs](https://www.openssl.org/docs/manmaster/man1/openssl-rand.html).

```shell showLineNumbers={false}
openssl rand -hex 32
```

### ENABLE_ADMIN_ROUTE

| Attribute        | Value   |
| :--------------- | :------ |
| Type             | boolean |
| Default          | false   |
| Required         | false   |
| CLI-configurable | false   |

> **Note**
>
> This variable has no effect on [Storefront Hosting](/developer/docs/storefront/catalyst/deployment/storefront-hosting/overview). BigCommerce handles `/admin` before requests reach your storefront and always redirects it to the store control panel, regardless of this setting.

This is a convenience feature for store admins.

When this option is set to `true`, the Catalyst storefront's admin URL at `https://store.example.com/admin` redirects to the store control panel at `https://store-{BIGCOMMERCE_STORE_HASH}.mybigcommerce.com/admin`. If `BIGCOMMERCE_STORE_HASH` isn't set, it redirects to `https://login.bigcommerce.com` instead. When this option isn't `true`, `/admin` redirects to the home page.

To make your control panel harder to find from the storefront, set this option to `false`.

If you wish to remove this feature entirely from your codebase, you can delete [`app/admin/route.ts`](https://github.com/bigcommerce/catalyst/blob/canary/core/app/admin/route.ts).

### MAKESWIFT_SITE_API_KEY

| Attribute        | Value                                  |
| :--------------- | :------------------------------------- |
| Type             | string                                 |
| Default          | no default                             |
| Required         | true, for Makeswift-connected projects |
| CLI-configurable | false                                  |

The `MAKESWIFT_SITE_API_KEY` environment variable determines which Makeswift site your storefront is connected to. [Makeswift-connected projects](/developer/docs/storefront/catalyst/makeswift/overview) fail to start without it. When deploying to production, you'll want to make sure this is set to the API key for your production Makeswift site. You can find the API key in the Makeswift dashboard by going to **Settings > Host**.

The Catalyst CLI doesn't write this key. [One-Click Catalyst](/developer/docs/storefront/catalyst/getting-started/one-click-catalyst) provisions the Makeswift sites, and the command your channel's dashboard gives you for local development includes the development site's key.

Setting this variable also changes the storefront's [Content Security Policy](/developer/docs/storefront/catalyst/reference/security#content-security-policy-csp): `frame-ancestors` allows the Makeswift editor origin, so the visual editor can load your storefront in a frame.

### MAKESWIFT_REVALIDATE_TARGET

| Attribute        | Value                                |
| :--------------- | :----------------------------------- |
| Type             | integer representing seconds         |
| Default          | `0` in development, `3600` otherwise |
| Required         | false                                |
| CLI-configurable | false                                |

Applies to Makeswift-connected projects only. Sets how long, in seconds, content fetched from Makeswift is cached before it's revalidated. Lower it if published Makeswift changes need to appear sooner, at the cost of more requests to Makeswift.

### NEXTAUTH_URL

| Attribute        | Value                                                                                     |
| :--------------- | :---------------------------------------------------------------------------------------- |
| Type             | string, URL                                                                               |
| Default          | If deployed on Vercel, the value of `VERCEL_PROJECT_PRODUCTION_URL`. Otherwise, no value. |
| Required         | false                                                                                     |
| CLI-configurable | false                                                                                     |

The public root URL of your storefront. Catalyst uses it as the base URL for the `Sitemap` line in `robots.txt`. On Vercel, it falls back to `VERCEL_PROJECT_PRODUCTION_URL`. On other hosts, set it explicitly so `robots.txt` points crawlers at the right sitemap.

Catalyst uses [Auth.js v5](https://authjs.dev/getting-started/deployment#environment-variables), which detects the request URL on its own and doesn't need this variable for sign-in. Behind a reverse proxy, see [`AUTH_TRUST_HOST`](#auth_trust_host).

### AUTH_TRUST_HOST

| Attribute        | Value     |
| :--------------- | :-------- |
| Type             | boolean   |
| Default          | undefined |
| Required         | false     |
| CLI-configurable | false     |

When set to `true`, Auth.js trusts the `X-Forwarded-Host` and `X-Forwarded-Proto` headers to determine the storefront's URL. Set this when your storefront runs behind a reverse proxy or load balancer on a host other than Vercel, where Auth.js would otherwise reject requests from an untrusted host. For details, see the [Auth.js deployment docs](https://authjs.dev/getting-started/deployment#auth_trust_host).

### TRAILING_SLASH

| Attribute        | Value   |
| :--------------- | :------ |
| Type             | boolean |
| Default          | true    |
| Required         | false   |
| CLI-configurable | false   |

This environment variable lets you choose your preferred URL appearance, with or without trailing slashes. This is purely cosmetic and has [no direct SEO implications, although it's a good idea to commit to one URL format](https://developers.google.com/search/blog/2010/04/to-slash-or-not-to-slash). Try not to create entity URLs with mixed cases of trailing slash and no-trailing slash—consistency is key.

The `TRAILING_SLASH` variable defaults to `true` and must be explicitly set to `false` to remove trailing slashes. If you set it to `false`, update your [Store Settings > URL Structure](https://login.bigcommerce.com/deep-links/manage/settings) in the store control panel. Note that this is a global setting, so the option you set will go into effect immediately on all the store's storefronts.

Catalyst uses the existing URLs of your BigCommerce objects, such as products and categories, as the URL paths on your storefront. Default [paths for BigCommerce products, categories, and so on](https://support.bigcommerce.com/s/article/Store-Settings#url-structure) create URLs with a trailing slash, while the [Next.js default behavior](https://nextjs.org/docs/app/api-reference/next-config-js/trailingSlash) does not use trailing slashes on URLs.

### DEFAULT_REVALIDATE_TARGET

| Attribute        | Value                        |
| :--------------- | :--------------------------- |
| Type             | integer representing seconds |
| Default          | 3600                         |
| Required         | false                        |
| CLI-configurable | false                        |

This environment variable sets the revalidation target, in seconds, for cached GraphQL Storefront API requests. Catalyst passes it as `next: { revalidate }` on cacheable requests, so cached data is refreshed at most this often.

Next.js persists cached queries in its [Data Cache](https://nextjs.org/docs/app/api-reference/functions/fetch#optionsnextrevalidate). Lower the value to show catalog changes sooner, at the cost of more API requests. Raise it to reduce API traffic.

### CLIENT_LOGGER

| Attribute        | Value                                            |
| :--------------- | :----------------------------------------------- |
| Type             | boolean                                          |
| Default          | `true` outside production, `false` in production |
| Required         | false                                            |
| CLI-configurable | false                                            |

This environment variable turns the [request logger](/developer/docs/storefront/catalyst/reference/client#logging) built into the Catalyst API client on and off.

When enabled, the client logger logs the following information:

* Which GraphQL operation is being performed; for example, `getProducts`.
* How long the request took in milliseconds.
* The complexity score of the GraphQL request payload, as indicated by the `X-Bc-Graphql-Complexity` response header.

Logging is on by default when `NODE_ENV` isn't `production`. Set `CLIENT_LOGGER` to `false` to turn it off in development, or to `true` to turn it on in production.

### BIGCOMMERCE_TRUSTED_PROXY_SECRET

> **Warning**
>
> This token is a **sensitive secret**. Do not expose outside environment variables.

| Attribute        | Value    |
| :--------------- | :------- |
| Type             | string   |
| Default          | no value |
| Required         | false    |
| CLI-configurable | false    |

Used for implementing BigCommerce's [Trusted Proxy Protocol](/developer/docs/storefront/headless), which helps secure communications and provides better rate limiting between BigCommerce and your storefront.

If BigCommerce has provided you with a Trusted Proxy secret, you may set it using this environment variable to have it automatically sent as a header on requests.

### CATALYST_TELEMETRY_DISABLED

| Attribute        | Value                                       |
| :--------------- | :------------------------------------------ |
| Type             | boolean                                     |
| Default          | undefined (telemetry is enabled by default) |
| Required         | false                                       |
| CLI-configurable | false                                       |

Controls whether telemetry metrics are collected when using the CLI. Set this to disable sending usage data. You can also use `npx @bigcommerce/catalyst telemetry enable/disable` to globally enable or disable telemetry collection.

### KV_LOGGER

| Attribute        | Value                                                  |
| :--------------- | :----------------------------------------------------- |
| Type             | boolean                                                |
| Default          | undefined (in production) or true (other environments) |
| Required         | false                                                  |
| CLI-configurable | false                                                  |

Enables or disables logging operations related to the Key-Value store database in the console. You can use this to help you understand how data is being cached or fetched.

Logging is disabled by default in production, but enabled on any other environment.

### KV_NAMESPACE

| Attribute        | Value                                                               |
| :--------------- | :------------------------------------------------------------------ |
| Type             | string                                                              |
| Default          | The value of `BIGCOMMERCE_STORE_HASH`, or `store` if that isn't set |
| Required         | false                                                               |
| CLI-configurable | false                                                               |

A prefix added to every key Catalyst writes to its KV store. Set it if several storefronts or environments share one KV store, so their cached route data doesn't collide.

### UPSTASH_REDIS_REST_URL

| Attribute        | Value       |
| :--------------- | :---------- |
| Type             | string, URL |
| Default          | no value    |
| Required         | false       |
| CLI-configurable | false       |

The REST URL of an [Upstash](https://upstash.com/) Redis database. When both this and `UPSTASH_REDIS_REST_TOKEN` are set, Catalyst caches route data in Upstash. Use this on hosts other than Storefront Hosting and Vercel, which provide a KV store automatically. Without a shared KV store, route data is cached only in memory, which isn't shared across server instances. See [Proxy](/developer/docs/storefront/catalyst/development/middleware#with-routes).

### UPSTASH_REDIS_REST_TOKEN

> **Warning**
>
> This token is a **sensitive secret**. Do not expose outside environment variables.

| Attribute        | Value    |
| :--------------- | :------- |
| Type             | string   |
| Default          | no value |
| Required         | false    |
| CLI-configurable | false    |

The REST token for the Upstash Redis database in `UPSTASH_REDIS_REST_URL`. Both must be set for Catalyst to use Upstash.

### NEXT_PUBLIC_BIGCOMMERCE_CDN_HOSTNAME

| Attribute        | Value                                       |
| :--------------- | :------------------------------------------ |
| Type             | string, comma-separated list of hostnames   |
| Default          | The CDN hostname from your store's settings |
| Required         | false                                       |
| CLI-configurable | false                                       |

Overrides the CDN hostnames Catalyst uses for store images. Catalyst reads this at build time, and also sends a `Link: rel=preconnect` header for each hostname. When it isn't set, Catalyst uses the CDN URL from your store's settings. Set it only if you serve images from a custom CDN configuration. This is a rare use case.

### BIGCOMMERCE_CLIENT_ID

> **Warning**
>
> This token is a **sensitive secret**. Do not expose outside environment variables.

| Attribute        | Value     |
| :--------------- | :-------- |
| Type             | string    |
| Default          | undefined |
| Required         | false     |
| CLI-configurable | false     |

Required when you use the [Customer Login API](/developer/docs/storefront/guides/customer-authentication/customer-login). This ID is obtained from your [BigCommerce API account](/developer/docs/overview/api-fundamentals/api-accounts) with the [Customer Login scope](/developer/docs/overview/api-fundamentals/api-accounts).

### BIGCOMMERCE_CLIENT_SECRET

> **Warning**
>
> This token is a **sensitive secret**. Do not expose outside environment variables.

| Attribute        | Value     |
| :--------------- | :-------- |
| Type             | string    |
| Default          | undefined |
| Required         | false     |
| CLI-configurable | false     |

Required alongside `BIGCOMMERCE_CLIENT_ID` if you use the [Customer Login API](/developer/docs/storefront/guides/customer-authentication/customer-login). This is the secret key from your [BigCommerce API account](/developer/docs/overview/api-fundamentals/api-accounts) with [Customer Login scope](/developer/docs/overview/api-fundamentals/api-accounts).

### ANALYZE

| Attribute        | Value     |
| :--------------- | :-------- |
| Type             | boolean   |
| Default          | undefined |
| Required         | false     |
| CLI-configurable | false     |

When set to `true`, enables [`@next/bundle-analyzer`](https://www.npmjs.com/package/@next/bundle-analyzer) during the build. The `pnpm build:analyze` script sets it for you. Useful for optimizing your application's bundle size and identifying large dependencies.

### BIGCOMMERCE_ACCESS_TOKEN

> **Warning**
>
> This token is a **sensitive secret**. Do not expose outside environment variables.

| Attribute        | Value                        |
| :--------------- | :--------------------------- |
| Type             | string                       |
| Default          | no value                     |
| Required         | false                        |
| CLI-configurable | with `--hosting bigcommerce` |

A store-level API account access token, for features that call BigCommerce's REST Management API from the server:

* The [Customer Group component](/developer/docs/storefront/catalyst/makeswift/customer-group-component) in Makeswift-connected projects uses it to list customer groups.
* [B2B Edition](/developer/docs/storefront/catalyst/experiments/b2b-edition) projects use it to call B2B APIs.
* [Testing](/developer/docs/storefront/catalyst/reference/testing) uses it to read, create, and clean up store data.

The Catalyst CLI writes it to `.env.local` when you create a project with `--hosting bigcommerce`. Otherwise, set it yourself, and give the API account only the scopes these features need.

### DISABLE_ANALYTICS

| Attribute        | Value                          |
| :--------------- | :----------------------------- |
| Type             | boolean                        |
| Default          | undefined (analytics are sent) |
| Required         | false                          |
| CLI-configurable | false                          |

When set to `true`, the storefront sends no analytics: no BigCommerce `VisitStarted` or `ProductViewed` events, no Google Analytics, no Script Manager scripts in the Analytics category, and no Vercel Analytics or Speed Insights. The `catalyst.visitorId`, `catalyst.visitId`, and `catalyst.productViews` cookies are removed from shoppers who already have them.

Set it at build time. The root layout reads it while prerendering, so a change takes effect on the next build.

### DISABLE_VERCEL_ANALYTICS

| Attribute        | Value                                    |
| :--------------- | :--------------------------------------- |
| Type             | boolean                                  |
| Default          | undefined (Vercel Analytics is included) |
| Required         | false                                    |
| CLI-configurable | false                                    |

When set to `true`, removes the [Vercel Web Analytics](https://vercel.com/docs/analytics) component from the storefront layout. Set it if you don't use Vercel Analytics, for example on Storefront Hosting.

### DISABLE_VERCEL_SPEED_INSIGHTS

| Attribute        | Value                                         |
| :--------------- | :-------------------------------------------- |
| Type             | boolean                                       |
| Default          | undefined (Vercel Speed Insights is included) |
| Required         | false                                         |
| CLI-configurable | false                                         |

When set to `true`, removes the [Vercel Speed Insights](https://vercel.com/docs/speed-insights) component from the storefront layout. Set it if you don't use Speed Insights, for example on Storefront Hosting.

### BIGCOMMERCE_GRAPHQL_API_DOMAIN

| Attribute        | Value               |
| :--------------- | :------------------ |
| Type             | string              |
| Default          | `mybigcommerce.com` |
| Required         | false               |
| CLI-configurable | false               |

The domain of the store's canonical URLs (`store-{hash}-{channelId}.{domain}`), used for GraphQL Storefront API requests, the sitemap, and the `/admin` redirect. Don't change it unless BigCommerce has told you to use a different environment.

### BIGCOMMERCE_ADMIN_API_HOST

| Attribute        | Value                 |
| :--------------- | :-------------------- |
| Type             | string                |
| Default          | `api.bigcommerce.com` |
| Required         | false                 |
| CLI-configurable | false                 |

The host for REST Management API requests. Don't change it unless BigCommerce has told you to use a different environment.