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://{BIGCOMMERCE_STORE_HASH}.mybigcommerce.com/manage

BIGCOMMERCE_ACCESS_TOKEN

This token is currently required; Catalyst requires this access token to make a few essential API calls to the Management API and the Customer Login API. This dependency will be removed in a future version of Catalyst.

The CLI will prompt you to enter this access token. The following steps will help you create the necessary API account and collect the access token.

Creating the access token

In the store's control panel, create a store-level API account (opens in a new tab) and add the following OAuth scopes. To learn more, see OAuth scopes (opens in a new tab).

The value of BIGCOMMERCE_ACCESS_TOKEN is the access token that's automatically generated when you create this API account.

Carts

The call to the carts feature of the Management API generates checkout redirect URLs. We will remove this dependency in a future version of Catalyst.

Customer Login

If you want to support checkout for signed-in customers, add the Customers Login scope so you can generate valid Customer Login JWTs to pass to the Customer Login API (opens in a new tab). To learn more, see BIGCOMMERCE_CLIENT_SECRET.

Information and Settings

As of this writing, Catalyst requires the Information & Settings read-only scopes to estimate shipping costs using the Management API.

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

BIGCOMMERCE_CLIENT_SECRET

You can use this API account client secret to sign Customer Login API (opens in a new tab) JWTs. Providing this value lets shoppers preserve their logged-in state when Catalyst redirects them to checkout.

You can use the client secret from the same API account you configured in BIGCOMMERCE_ACCESS_TOKEN, or configure a dedicated API account with the following scope.

To learn more, see any of the following docs:

• Customer Login in this reference
• Guide to the Customer Login API (opens in a new tab), which describes how to make the necessary JWT
• Reference for the endpoint to Log a customer in (opens in a new tab), which describes how to send the JWT to BigCommerce

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://{BIGCOMMERCE_STORE_HASH}.mybigcommerce.com/admin.

In production, setting this option to false improves the security posture of the storefront.

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.

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