Build an Integration

This page shows how to build a Catalyst integration for your technology and contribute it to the Catalyst repository, so store owners can add it to their composable commerce stack. For general guidelines on contributing to Catalyst, including bug fixes and features, see CONTRIBUTING.md in the Catalyst repository.

Catalyst integrations vary in size and complexity; some Catalyst integrations may communicate with third-party APIs and work best when paired with a related app from the BigCommerce App Marketplace, while others are as small as installing a package from npm.

Integrations maintained in the Catalyst upstream repository live on integrations/* branches, such as integrations/makeswift and integrations/b2b-makeswift. You can browse them all in the list of integration branches on GitHub.

The steps below cover setting up your development environment, building a minimal reference implementation of your technology into Catalyst, contributing it upstream, and keeping it up to date.

Set up your development environment

The default branch of the Catalyst repository is canary, where active development happens. Since you’ll ultimately be contributing code back up to the Catalyst upstream GitHub repository, create a new branch off of upstream/canary in your local Catalyst fork:

git fetch upstream canary
git checkout -b integrations/<INTEGRATION_NAME> upstream/canary

Then write the code your integration needs.

Build your integration

Follow these practices, which come from the Catalyst team’s experience building integrations:

1. Keep your integration code as maintainable as possible. Keep the integration-specific changes small and contained, outside of files that change often in canary where you can. The fewer files your integration touches, the fewer merge conflicts you’ll need to resolve each time you pull in the latest changes from upstream/canary.
2. Explicitly call out when your integration makes use of newly introduced environment variables. For example, the integrations/makeswift branch adds a new environment variable called MAKESWIFT_SITE_API_KEY; by explicitly listing newly introduced environment variables in a version-controlled file like .env.example, it makes it obvious to the consumers of your integration when they need to add new environment variables to make your integration work.

Open a PR to add your integration upstream

When your branch is ready for public use, open a new issue in the Catalyst upstream GitHub repository. In your issue, request the creation of an integrations/<INTEGRATION_NAME> branch. Once the branch is created, you can target it with your pull request to contribute your integration code back upstream.

Keep your integration up to date

An integration branch should mirror canary apart from its own integration code, so keep it in sync by merging the latest canary into it rather than rebasing. Create a sync branch from your integration branch, merge upstream/canary, and resolve any conflicts:

git fetch upstream
git checkout -B sync-integrations-<INTEGRATION_NAME> upstream/integrations/<INTEGRATION_NAME>
git merge upstream/canary
git push origin sync-integrations-<INTEGRATION_NAME>

Then open a PR from your fork’s sync-integrations-<INTEGRATION_NAME> branch into the upstream integrations/<INTEGRATION_NAME> branch. Don’t squash or rebase-and-merge this PR: it must land as a true merge commit, so that it establishes a new merge base between canary and your integration branch and you don’t resolve the same conflicts again next time.

For the full procedure the Catalyst team follows to keep integrations/makeswift in sync with canary, see Keeping integrations/makeswift in sync with canary in CONTRIBUTING.md.

Next steps

• Read CONTRIBUTING.md for the review process and general contribution guidelines.
• Browse the existing integration branches for examples of how other integrations are structured.