Getting Started

Build an integration

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 API's and work best when paired with a related app from the BigCommerce App Marketplace (opens in a new tab), 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 (opens in a new tab)

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.

Setting up your integration development environment

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:

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

Now, you can begin to write the code required to make your integration work!

Building your integration

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.

1. Keep your integration code as maintainable as possible. You'll notice that the integrations/makeswift branch (opens in a new tab) 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.
2. Explicitly call out when your integration makes use of newly introduced environment variables. You'll notice that the integrations/makeswift branch (opens in a new tab) 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 to upstream

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

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.

git checkout integrations/<INTEGRATION_NAME>
git fetch upstream main
git pull --rebase upstream main
git push --force-with-lease origin integrations/<INTEGRATION_NAME>