Reference
The following reference lists the environment variables that a Catalyst storefront can use, along with a description of their data types and approximate values.
Catalyst storefronts require the following variables to function.
Note
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.
| Attribute | Value |
|---|---|
| Type | string |
| Permanently required | true |
| CLI-configurable | true |
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/manageCaution
This token is a sensitive secret. Do not expose outside environment variables.
| Attribute | Value |
|---|---|
| Type | string |
| Permanently required | false |
| CLI-configurable | true |
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.
In the store's control panel, create a store-level API account and add the following OAuth scopes. To learn more, see OAuth scopes.
| UI Name | Permission | Parameter | Required |
|---|---|---|---|
| Carts | modify | store_cart |
true. See Carts. |
| Customers Login | modify | store_v2_customers_login |
false. See Customer Login. |
| Information & Settings | read-only | store_v2_information_read_only |
true. See Information and Settings. |
The value of BIGCOMMERCE_ACCESS_TOKEN is the access token that's automatically generated when you create this API account.
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.
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. To learn more, see BIGCOMMERCE_CLIENT_SECRET.
As of this writing, Catalyst requires the Information & Settings read-only scopes to estimate shipping costs using the Management API.
Caution
This token is a sensitive secret. Do not expose outside environment variables.
| Attribute | Value |
|---|---|
| Type | string |
| Permanently required | true |
| CLI-configurable | true |
This bearer token authorizes access to the GraphQL Storefront API 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.
| UI Name | Permission | Parameter |
|---|---|---|
| Storefront API Customer Impersonation Tokens | modify | store_storefront_api_customer_impersonation |
| Attribute | Value |
|---|---|
| Type | integer |
| Permanently required | true |
| CLI-configurable | true |
This numeric channel ID specifies which sales channel 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.
Caution
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.
openssl rand -hex 32Catalyst does not require the following values, but we recommend setting them for optimal performance.
Caution
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 | true |
Providing a pseudo-random hex string for this environment variable lets you use the Turborepo Remote Cache feature with signed artifacts, 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.
openssl rand -hex 32Caution
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 | true |
You can use this API account client secret to sign Customer Login API 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.
| UI Name | Permission | Parameter |
|---|---|---|
| Customers Login | modify | store_v2_customers_login |
To learn more, see any of the following docs:
- Customer Login in this reference
- Guide to the Customer Login API, which describes how to make the necessary JWT
- Reference for the endpoint to Log a customer in, which describes how to send the JWT to BigCommerce
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.
| Attribute | Value |
|---|---|
| Type | boolean |
| Default | false |
| Required | false |
| CLI-configurable | false |
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.
| Attribute | Value |
|---|---|
| Type | string, URL |
| Default | If deployed on Vercel, identical to VERCEL_URL. Otherwise, no value. |
| Required | false |
| CLI-configurable | false |
The NEXTAUTH_URL environment variable tells the Auth.js library the root URL of the storefront.
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.
| 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. 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 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. create URLs with a trailing slash, while the Next.js default behavior does not use trailing slashes on URLs.
| Attribute | Value |
|---|---|
| Type | integer representing seconds or boolean: false |
| Default | 0 |
| Required | false |
| CLI-configurable | false |
This environment variable sets a sensible revalidation target for cached requests.
NextJS persists cached queries in its data cache. By default, the time persisted is not defined. For more information on how revalidate works, see next.revalidate.
| Attribute | Value |
|---|---|
| Type | boolean |
| Default | false |
| Required | false |
| CLI-configurable | true |
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-Complexityresponse header.
| Attribute | Value |
|---|---|
| Type | integer |
| Default | 50 |
| Required | false |
| CLI-configurable | false |
This environment variable sets a limit on the number of JS chunks webpack will generate via the LimitChunkCountPlugin in next.config.js. Generally speaking, using more chunks can improve performance, but will increase the number of requests to the origin to download these files. For hosts that charge for each asset request, this may make your site more expensive to serve. You can decrease this number to decrease the number of individual JS files that will be requested on each page, but each file will be larger, which may decrease Lighthouse scores due to more time spent on script parsing and more unused JS code in each chunk on a given page.