For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Before diving into information regarding Catalyst-compatible apps, it’s important to explicitly define some important terms:
Glossary
App: When we refer to an “app” in this guide, we are referring to a Single-Click Application which you can find listed in the BigCommerce app marketplace.
Storefront Apps: Storefront apps are a type of app focused on modifying or enhancing the user experience on the rendered storefront, often via script injection or widget rendering, using APIs such as the Scripts API or Widgets API.
Characteristics:
Modify storefront behavior or appearance (e.g., popups, badges, live chat)
Inject JavaScript or HTML/CSS into the storefront
Often depend on Stencil-specific DOM structure or Stencil Theme Objects
Incompatible or partially functional on headless storefronts (unless they provide APIs or SDKs)
Back-Office Apps: Back-office apps interact primarily with BigCommerce’s APIs (e.g., Products, Orders, Customers, Catalog, etc.) to modify or consume store data, but do not directly alter the rendering or behavior of the storefront itself.
Characteristics:
No dependency on the DOM structure of the storefront or Stencil Theme Objects
May affect what data is available on the storefront but not how it’s rendered or how users interact with it
Examples:
Inventory sync tools
ERP integrations
Integration: When we refer to an “integration,” we are referring to custom logic that has been added to your e-commerce operations to help connect your store to the outside world. In other words, an App is a type of integration.
What do I need to do to reach Catalyst-compatibility?
Below are a series of use cases that will help you identify what you need to do to make your app compatible with Catalyst storefronts.
I have a back-office app that I think may be compatible with Catalyst out of the box.
It’s likely that your app or integration is already compatible with Catalyst if it is a backend integration and that there are no major changes needed.
How can I ensure my app/integration is compatible with Catalyst?
Set up a Catalyst storefront in your Control Panel.
If you meet all criteria and believe your app is compatible, begin the verification process.
I am the maintainer of an existing Single-Click App and want to determine if my app is compatible with Catalyst.
Follow these steps:
Is your Single-Click App Multi-Storefront compatible?
Catalyst requires its own storefront channel, so your app must be Multi-Storefront compatible.
If not, make your app MSF compatible first.
If it is, proceed to Step 2.
Does your app modify the storefront?
If not, it may already be Catalyst-compatible.
Test it by creating a Catalyst storefront and verifying functionality.
If yes, proceed to Step 3.
How does your app modify the storefront?
If via Scripts, proceed to Step 4.
If via Widgets, proceed to Step 5.
My app modifies the storefront through the use of Scripts.
If your script does not rely on the Stencil DOM or Stencil APIs, it may be compatible.
Test on a Catalyst storefront to confirm functionality.
My app modifies the storefront through the use of Widgets.
Since Widgets and Page Builder functionalities in Stencil stores do not exist in Catalyst, apps relying on these will need redevelopment.
Consider using Makeswift as a flexible alternative for component management.
I am the developer of a net-new Single-Click App, and want to ensure my app is compatible with Catalyst.
Follow these steps:
Understand Catalyst’s Architecture
Catalyst uses Next.js and React components for storefront UI.
Familiarize yourself with routing, data fetching, and state management.
Assess Your App’s Role
Determine if your integration functions independently of the storefront.
If it modifies the storefront, decide on delivery method (NPM package, external script, etc.).
Test in a Catalyst Environment
Deploy a Catalyst storefront locally and test thoroughly.
Document the Integration
Provide clear setup instructions for merchants.
Submit Updates to the Marketplace
Highlight Catalyst compatibility and test for performance and accessibility benchmarks.
How will users know my app is Catalyst-compatible?
Catalyst-compatible apps in the App Marketplace include a badge indicating Catalyst compatibility.
When creating or updating your app in the Developer Portal, you can specify Catalyst as a supported feature.
Our App Marketplace team will review your app compatibility, follow up with any feedback (if necessary), and add the badge once approved.
Leverage our BigCommerce Developer ecosystem to learn more
