Deploying Your Catalyst Storefront
Your Catalyst storefront initially comes with a free, hosted preview environment so you can explore the full user experience right away. However, this preview environment cannot be used to deploy your own custom code, nor can it be used for a transacting production storefront.
Once you’re ready to take your own custom Catalyst codebase online, whether in a pre-release or full production state, the following steps will be required in order to transition from the preview environment to your own hosted Next.js application.
Choose a Hosting Provider
Vercel provides a fully optimized platform for the Next.js features utilized by Catalyst, as well a streamlined deployment process. However, Catalyst can be hosted on a number of other cloud platforms that support Next.js applications.
See the Catalyst documentation for details on the Next.js features that must be supported by your host.
Deploy Your Project
Deploy your custom Catalyst code to your chosen provider.
Make sure to configure the appropriate environment variables (the names of which are found in your .env.local file) to ensure your project is connected to your BigCommerce store.
Note that if using Makeswift, you should use the API key of your primary Makeswift site for MAKESWIFT_SITE_API_KEY, instead of the “dev” site API key from your local environment. (See the “Host” tab of your Makeswift site settings.)
Configure KV Store
IF using a hosting provider other than Vercel, connect a KV database to handle caching the results of of GraphQL route and store status queries. This is essential to maintain optimal page performance as traffic to the storefront scales.
Update DNS for Primary Domain
Update your DNS settings to point your store’s domain to your deployed Catalyst application.
Remember that your primary domain should be pointed to the provider where Catalyst is deployed, not to BigCommerce’s name servers! Follow your hosting provider’s guidelines for configuring DNS.
If you’re using a domain purchased from BigCommerce, see DNS management details in the knowledge base.
Update the Channel Site URL
Update the Channel Site for your storefront to the appropriate primary URL.
This can be done via the API or in your store control panel.
Once this step is completed, generated links to your storefront from the control panel, transactional emails, or BigCommerce-hosted pages will lead to your own hosted front-end. The preview environment will no longer be used.
Update the Makeswift Site URL
In addition to updating your BigCommerce channel’s primary URL, you must update the corresponding setting in Makeswift.
In your Makeswift Site settings, update the Host URL to match your primary domain.
Update DNS for Checkout Subdomain
If you are using Redirected Checkout, you must also make sure to properly configure DNS for your checkout subdomain.
In this case, the appropriate DNS record must be pointed to BigCommerce using one of the techniques described in the knowledge base.
The domain configured for checkout must be a subdomain of your primary domain (for example, checkout.mystore.com).
Upsert the Checkout URL
If you are using Redirected Checkout, upsert the checkout URL on your Channel Site with your selected checkout subdomain.
This can be done via the API or in your store control panel.
Note that an SSL certificate will automatically be provisioned for the subdomain that you upsert as your checkout URL.
Update Site Routes
If you have changed any of the routes for standard pages in your Catalyst application, resulting in URL paths different than the default, make sure to update your Site Routes accordingly in BigCommerce to ensure that generated links are correct.
This can be done via the API or in your store control panel.
