From the entire Catalyst team, we’re excited to build alongside you! Being an integration developer means making it easier and more accessible for merchants to adopt your technology into their composable commerce stack.
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 other Catalyst integrations may be as simple as installing a package from NPM.
No matter the size of your integration, one thing that all Catalyst integrations have in common is that they contain reference code pushed to a branch on the Catalyst upstream repository. This makes it easy to browse every single Catalyst integration in one location:
https://github.com/bigcommerce/catalyst/branches/all?query=integrations%2F
This section will guide you through setting up your integration development environment, building a minimal reference implementation of your technology into Catalyst, and finally how to pull in updates from the upstream Catalyst repository to keep your integration up to date.
By the end of this section, you’ll be on your way to having your integration listed in the link above.
Since you’ll ultimately be contributing code back up to the Catalyst upstream GitHub repository, it makes the most sense for you to create a new branch off of upstream/main in your local Catalyst fork:
Now, you can begin to write the code required to make your integration work!
There are a handful of lessons we have learned from building integrations into Catalyst ourselves; we wanted to offer those lessons as tips to follow while building your own integration. You should highly consider incorporating these tips into your own workflow, as we have found it has saved us time and headache.
integrations/makeswift branch has only a single commit, and about 20 changed files. This means that merge conflicts caused rebasing on top of the latest upstream/main to update your integration are easier to deal with.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.Now that your branch is ready for public use, please start by opening 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.
Keeping your integration up to date is as simple as rebasing your integration branch on top of the latest changes introduced to upstream/main, and then opening a PR from your origin remote fork integration branch into the integration branch with the same name on the upstream remote repository.