Building Catalyst-Compatible Apps and Integrations

If you have an existing app or integration in the BigCommerce App Marketplace that you offer for existing BigCommerce stores, it is possible that your app may not work out of the box with Catalyst. For example, if your app makes use of Script Manager, or Stencil Context Objects, your app will likely not function properly if loaded on a Catalyst storefront by default. Prioritize integrations that enhance the shopper experience, as these have the greatest impact on site performance and usability.

Integration compatibility

• Backend integrations:
  Backend integrations listed in the BigCommerce App Marketplace likely do not require enhancements to support Catalyst.
• Frontend integrations:
  Frontend integrations listed in the BigCommerce App Marketplace are likely not Catalyst-compatible, as they interact with or affect frontend storefront code.

Why Catalyst?

Catalyst supports server-side app code placement, aligning with modern web development best practices for scalability and performance.

How will users know my app is Catalyst-compatible?

We are currently working to design the UX that will indicate Catalyst compatibility within the BigCommerce App Marketplace.

Common use cases

Below are some common use cases for apps and integrations when considering Catalyst compatibility. If your use case is not accounted for, please reach out to our DevRel team for assistance.

I have a new Catalyst storefront and I want to add the apps and integrations I had before

• How do I know which apps/integrations are supported/compatible with Catalyst?
  Apps updated for Catalyst compatibility should include a flow for Catalyst storefront users/owners to install and configure them.

• Where is the list of all apps/integrations available for my new Catalyst storefront?
  As of today, there is no such list.

I have a backend app/integration

• Compatibility:
  Your app or integration is likely already compatible with Catalyst if it is a backend integration.

• Ensuring compatibility:
  Set up a Catalyst storefront in your Control Panel to verify functionality.

I have an app/integration that interacts with the frontend

Efforts to improve app compatibility with Catalyst storefronts should focus on:

• Enhancing APIs for script retrieval and execution.
• Providing alternatives to Stencil-specific features like DOM structures and object variables.
• Investigating performance optimization strategies such as Partytown (opens in a new tab).
• Supporting app developers in adapting their solutions to Catalyst’s architecture.

Recommendation for dual versions

Instead of maintaining two separate apps in the marketplace:

• Query the Channels endpoint during installation to determine whether a storefront is Catalyst.
• Provide guidance for users to implement on Catalyst storefronts.

Apps modifying the storefront via widgets

• Observation: Some apps (e.g., Algolia) create Widgets during installation using the Widgets API.
• Compatibility Issue: Widgets and Page Builder are not available in Catalyst.

Apps modifying the storefront via Script Manager

• Details:
  • Scripts are injected into storefronts using the Script Manager API.
  • Compatibility depends on script functionality.
• Potential solutions for Catalyst:
  • Fetching Scripts: Mimic Stencil’s “fetch and run” model.
  • Running Scripts: Add predefined DOM nodes or attributes for common integration points.

Stencil Object Variables

• Issue: Scripts may rely on Stencil Object variables for dynamic data.
• Solution: Provide alternative methods to expose data in Catalyst.

Performance implications

• Optimization strategies:
  • Minimize client-side JavaScript.
  • Explore tools like Partytown to reduce strain on the main thread.

I am building a net-new Catalyst-compatible app or integration

Steps to integrate with Catalyst:

1. Understand Catalyst's architecture

   • Leverage Next.js for server-side rendering and React for UI components.
   • Familiarize yourself with the Catalyst codebase.

2. Assess your app's role

   • Data integrations
   • UI/UX enhancements
   • Operational tools

3. Update APIs and endpoints

   • Use the latest Storefront GraphQL API.
   • Optimize for Catalyst’s SSR and caching.

4. Develop Catalyst-compatible components

   • Build reusable React components adhering to Catalyst’s design.

5. Implement authentication and authorization

   • Use Catalyst's middleware or API routes for secure authentication.

6. Optimize for performance

   • Focus on SSR and static site generation (SSG).

7. Test in a Catalyst environment

   • Deploy a Catalyst storefront locally and test extensively.

8. Document the integration

   • Provide clear setup instructions and troubleshooting tips.

9. Submit updates to the App Marketplace

   • Highlight Catalyst compatibility and meet performance benchmarks.

Leveraging the BigCommerce developer ecosystem for success

• Join the BigCommerce Developers Slack (opens in a new tab) to collaborate and share ideas.
• Align with Catalyst’s roadmap through community engagement.
• Write about your integration experience for the Resource Hub (opens in a new tab) and the monthly developer newsletter.