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_CUSTOMER_IMPERSONATION_TOKEN

This bearer token authorizes access to the GraphQL Storefront API (opens in a new tab) and supports operations that request 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 customer impersonation 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).

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

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.