Reference

Environment variables

The following reference lists the environment variables that a Catalyst storefront can use, along with a description of their data types and approximate values.

Required

Catalyst storefronts require the following variables to function.

BIGCOMMERCE_STORE_HASH

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

The store hash is visible as part of the store's canonical URL, and you can also locate the store hash in the control panel URL, which takes the following form.

https://store-{BIGCOMMERCE_STORE_HASH}-{channelId}.mybigcommerce.com/manage

You will not see the {channelId} portion of your canonical URL when viewing the control panel. 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 (opens in a new tab).

BIGCOMMERCE_STOREFRONT_TOKEN

This bearer token authorizes access to the GraphQL Storefront API (opens in a new tab). It is used to generate the customer access token for requesting information specific to individual customers, such as getting wishlist items.

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 storefront token (opens in a new tab).

BIGCOMMERCE_CHANNEL_ID

This numeric channel ID specifies which sales channel (opens in a new tab) 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

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 (opens in a new tab).

openssl rand -hex 32

Recommended

Catalyst does not require the following values, but we recommend setting them for optimal performance.

TURBO_REMOTE_CACHE_SIGNATURE_KEY

Providing a pseudo-random hex string for this environment variable lets you use the Turborepo Remote Cache feature with signed artifacts (opens in a new tab), 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 (opens in a new tab).

openssl rand -hex 32

Optional

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

ENABLE_ADMIN_ROUTE

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 opens the store control panel at the store's canonical URL, https://store-{BIGCOMMERCE_STORE_HASH}-{channelId}.mybigcommerce.com/admin.

You may set this option to false if you wish to improve the security posture of the storefront by obscuring access to your control panel.

If you wish to remove this feature entirely from your codebase, you can delete admin/route.ts (opens in a new tab).

MAKESWIFT_SITE_API_KEY

The MAKESWIFT_SITE_API_KEY environment variable determines which Makeswift site your storefront is connected to. 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 in the Makeswift dashboard by going to to Settings > Host.

NEXTAUTH_URL

The NEXTAUTH_URL environment variable tells the Auth.js library the root URL of the storefront (opens in a new tab).

If your storefront is deployed on Vercel, NEXTAUTH_URL is automatically detected from VERCEL_URL, but for other environments, you should set NEXTAUTH_URL explicitly.

TRAILING_SLASH

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 (opens in a new tab). 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 (opens in a new tab) 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, etc. (opens in a new tab) create URLs with a trailing slash, while the Next.js default behavior (opens in a new tab) does not use trailing slashes on URLs.

DEFAULT_REVALIDATE_TARGET

This environment variable sets a sensible revalidation target for cached requests.

NextJS persists cached queries in its data cache (opens in a new tab). By default, the time persisted is not defined. For more information on how revalidate works, see next.revalidate (opens in a new tab).

CLIENT_LOGGER

This environment variable turns the request logger 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.

BIGCOMMERCE_TRUSTED_PROXY_SECRET

Used for implementing BigCommerce's Trusted Proxy Protocol (opens in a new tab), 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

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

KV_LOGGER

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.

NEXT_PUBLIC_BIGCOMMERCE_CDN_HOSTNAME

Used when merchants need to host images outside the default BigCommerce CDN. This is a rare use case, typically only needed if you use a custom CDN configuration.

BIGCOMMERCE_CLIENT_ID

Required when you use the Customer Login API (opens in a new tab). This ID is obtained from your BigCommerce API account (opens in a new tab) with the Customer Login scope (opens in a new tab).

BIGCOMMERCE_CLIENT_SECRET

Required alongside CLIENT_ID if you use the Customer Login API (opens in a new tab). This is the secret key from your BigCommerce API account (opens in a new tab) with Customer Login scope (opens in a new tab).

ANALYZE

When set to 'true', enables webpack bundle analysis during build. Useful for optimizing your application's bundle size and identifying large dependencies.