Environment Variables
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.
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
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:
The store hash is also part of each channel’s canonical URL, which adds the channel ID:
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.
BIGCOMMERCE_STOREFRONT_TOKEN
This token is a sensitive secret. Do not expose outside environment variables.
This is a GraphQL Storefront API private bearer token that authorizes server-to-server access to the 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:
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.
BIGCOMMERCE_CHANNEL_ID
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.
AUTH_SECRET
This token is a sensitive secret. Do not expose outside environment variables.
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.
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
This token is a sensitive secret. Do not expose outside environment variables.
This is a GraphQL Storefront API private bearer token limited to the Unauthenticated scope. Catalyst’s GraphQL proxy uses it to forward GraphQL requests that client-side libraries make through your storefront domain, such as 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, 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:
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.
The GraphQL proxy was added in Catalyst 1.7.0.
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
This token is a sensitive secret. Do not expose outside environment variables.
This variable applies only to 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, 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.
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 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.
MAKESWIFT_SITE_API_KEY
The MAKESWIFT_SITE_API_KEY environment variable determines which Makeswift site your storefront is connected to. Makeswift-connected projects 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 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: frame-ancestors allows the Makeswift editor origin, so the visual editor can load your storefront in a frame.
MAKESWIFT_REVALIDATE_TARGET
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
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, 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
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.
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. 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, and so on create URLs with a trailing slash, while the Next.js default behavior does not use trailing slashes on URLs.
DEFAULT_REVALIDATE_TARGET
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. Lower the value to show catalog changes sooner, at the cost of more API requests. Raise it to reduce API traffic.
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-Complexityresponse 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
This token is a sensitive secret. Do not expose outside environment variables.
Used for implementing BigCommerce’s Trusted Proxy Protocol, 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/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.
KV_NAMESPACE
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
The REST URL of an Upstash Redis database. When both this and UPSTASH_REDIS_REST_TOKEN are set, Catalyst caches route data in Upstash. Use this on hosts other than Native 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.
UPSTASH_REDIS_REST_TOKEN
This token is a sensitive secret. Do not expose outside environment variables.
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
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
This token is a sensitive secret. Do not expose outside environment variables.
Required when you use the Customer Login API. This ID is obtained from your BigCommerce API account with the Customer Login scope.
BIGCOMMERCE_CLIENT_SECRET
This token is a sensitive secret. Do not expose outside environment variables.
Required alongside BIGCOMMERCE_CLIENT_ID if you use the Customer Login API. This is the secret key from your BigCommerce API account with Customer Login scope.
ANALYZE
When set to true, enables @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
This token is a sensitive secret. Do not expose outside environment variables.
A store-level API account access token, for features that call BigCommerce’s REST Management API from the server:
- The Customer Group component in Makeswift-connected projects uses it to list customer groups.
- B2B Edition projects use it to call B2B APIs.
- 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 commerce. Otherwise, set it yourself, and give the API account only the scopes these features need.
DISABLE_VERCEL_ANALYTICS
When set to true, removes the Vercel Web Analytics component from the storefront layout. Set it if you don’t use Vercel Analytics, for example on Native Hosting.
DISABLE_VERCEL_SPEED_INSIGHTS
When set to true, removes the Vercel Speed Insights component from the storefront layout. Set it if you don’t use Speed Insights, for example on Native Hosting.
BIGCOMMERCE_GRAPHQL_API_DOMAIN
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
The host for REST Management API requests. Don’t change it unless BigCommerce has told you to use a different environment.