Getting Started

Customize a storefront

As a storefront developer, your next steps will involve customizing and building Catalyst on top of the main branch in your fork of the Catalyst repository. This section will guide you through setting up your storefront development environment, making your first customizations to your storefront, and pulling in updates from the upstream Catalyst repository.

Setting up your storefront development environment

You will be making your customizations directly on the main branch of your fork. This means your main will contain both upstream updates and your own changes. This approach is straightforward but requires careful merging when pulling in updates from the upstream.

Making your first code customization

For example purposes, let's make a small code change to simulate what a real storefront development workflow might look like when working in Catalyst.

First, open the following file in your text editor: core/package.json

Next, find the "name" property inside the JSON object towards the top of the file. Replace its value "@bigcommerce/catalyst-core" with the name of your storefront project:

{
  "name": "my-store-name"
  // ...
}

Save the file so that we can commit those changes.

From the root of the monorepo, add your change by running:

git add -p

Commit your change by running:

git commit -m "updated project name"

Finally, push your changes to your remote by running:

git push origin main

Note

In a real development workflow, you might have set up continuous deployment to run whenever code is pushed to the main branch of your remote fork; if that was the case, then at this point your changes would likely be automatically deployed to production.

Congratulations! You've just written, committed, and pushed your very first customization to your Catalyst storefront project.

Pulling in updates from the upstream

Now that the main branch on your fork (also referred to as origin/main) has diverged from the main branch on the upstream repository (also referred to as upstream/main), we should talk about how we recommend keeping your Catalyst project up to date.

First, let's check to see if any updates have been pushed to the upstream Catalyst repository recently. Run the following command to fetch the latest upstream changes:

git fetch upstream main

If you see output similar to what's below, your Catalyst fork is up to date with the upstream Catalyst repository. You can continue building your storefront.

From github.com:bigcommerce/catalyst
 * branch            main       -> FETCH_HEAD

On the other hand, if you see output closer to what's below, your Catalyst fork is out of date, and it might be a good idea to update it.

remote: Enumerating objects: 5, done.
remote: Counting objects: 100% (5/5), done.
remote: Compressing objects: 100% (1/1), done.
remote: Total 3 (delta 2), reused 3 (delta 2), pack-reused 0 (from 0)
Unpacking objects: 100% (3/3), 511 bytes | 255.00 KiB/s, done.
From github.com:bigcommerce/catalyst
 * branch            main       -> FETCH_HEAD
   abcd123..efgh456  main       -> upstream/main

If you would like to update your Catalyst fork, simply merge the upstream changes into your main branch:

git checkout main
git merge upstream/main

You'll be prompted to enter a commit message. We recommend a commit message similar to "Pull Catalyst upstream updates MM/DD/YYYY". Save your message and run the previous command to check for updates:

git fetch upstream main

Your local Catalyst project is now up to date!

Important

Resolving all merge conflicts after pulling in updates should not be your only indicator that the updates did not introduce regressions when coupled with your customizations. We recommend multiple forms of testing and QA before deploying to production in general, but especially after pulling in new updates from the Catalyst upstream repository.

Consuming Catalyst integrations

There are a number of integration branches containing sample code for a wide variety of use cases in the Catalyst upstream repository:

https://github.com/bigcommerce/catalyst/branches/all?query=integrations%2F (opens in a new tab)

Generally speaking, Catalyst integrations are just branches available in the upstream GitHub repository that can be checked out locally; so in order to evaluate an integration locally, you can use the standard Git workflow to create a new local branch from a remote upstream branch:

git fetch upstream <INTEGRATION_BRANCH>
git checkout -b <INTEGRATION_BRANCH> upstream/<INTEGRATION_BRANCH>

You can explore and run the code locally on this branch. If you like what you see, you can copy & paste the code that you find most beneficial to your custom storefront build back into your main branch.

Next steps

Now that you feel confident customizing and updating your Catalyst storefront, we recommend reading our documentation on styling your storefront, fetching data from your storefront, creating components for your storefront, and deploying your storefront.

Installation Build an integration