With the addition of new features and functionality within Swell, we make periodic updates to our storefronts to support these new features. Implementing updates to your storefront can be done with the use of git and your terminal. Configuring your git repo will also enable you to directly edit your storefront theme's code—allowing further customization than what's possible within the storefront's visual editor.

In order for you to directly access and change the code of your theme, you will need to create a repo for your storefront's theme and make changes to the code from within the repo. From there, you can push your changes live as well as use your repo to get the latest updates to support storefront updates and new functionalities.

The first step will be generating your SSH key. See GitHub's SSH key docs for additional information on generating your SSH key. Once generated, add the key and a key name to your SSH keys.

After adding the SSH key from within your terminal, clone your personal storefront repo—this will clone all of your current settings that have been configured within your dashboard.

You can find the command to clone your store repo on the Storefront > Developer tools page in the Git management section. It will look something like this:

git clone git@swell.store:your-store-id.git

To view your recently cloned storefront repo, use the following command (this is also listed within Storefront > Developer tools).

cd your-store-id/

You will see your store configuration and settings reflected within your cloned storefront. Additionally, you can further customize your storefront's theme code from your git repository and push updates from your repo now that it has been created.

You can push any changes made to your theme's repo live with the following command:

git push

You will also need to view and publish the changes live from within the storefront editor once the updates have been pushed to your storefront. Once you have published the changes within the editor, your storefront will reflect your most recent updates to the theme.

In addition to setting up your repo for customization, you can also merge it with the Swell theme's public project to receive updates that may have been released for your storefront theme. This could include new functionality, bug fixes, and other similar changes to the base theme that will need to be added through a merge to your master branch. Check out our guide for updating Swell themes directly from the dashboard for more details.

Copy the Clone HTTPS URL, and add a remote theme with the copied URL for your storefront repo. For example, if we are updating Origin, we'd use https://github.com/swellstores/origin-theme.git.

git remote add theme (paste the URL here)

Fetch the theme to get the most up to date branches and commits from the Swell public repo:

git fetch theme

Now that we've got the current Swell storefront theme, we're ready to merge with our master branch.

Merge the Swell theme to your store's master branch:

git merge theme/master

You may encounter conflicts depending on how recent your Origin version is. If this is the case, resolve the conflicts to facilitate the merge.

Open the code editor to resolve the conflicts with the following command

code . 

This command may need to be installed. Press Shift + Cmd+ P (or Shift + Ctrl + P) to open the Command Palette. Search 'Install command' and install the code command in PATH.

Review and accept the changes to continue the merge process and save. Your repo will be up to date once the merge completes.

Performing a git log will confirm the merge was completed successfully:

git log

You should see a result within your log like this one:

Merge remote-tracking branch 'theme/master'

Now let's get the new storefront version live. Initiate the update with the following command:

git push

This may take a moment to finish—usually about 5 minutes or so. You should see a success message along with some additional instructions within the console once the process has been completed.

The last step here is to go to your storefront editor to publish the updates to your live storefront. Navigate to the storefront editor and press publish.

You may encounter a scary 500 message, but refreshing the instance of the editor will resolve this and display your new, up-to-date storefront.

Once your updates have been published, you're all set. Your storefront will have retained your settings and configurations along with having the most recent build.

Once you have created your storefront with a Swell theme, we host a container that has a dedicated git repository.

When implementing custom changes to your storefront theme through development rather than the storefront editor, there are some best practices that should be taken into account in order to streamline the git management of your theme.

Also, note that handling CORS might be necessary if making external requests—depending on the type of server, this may require setup with a custom domain to work.

To pull the latest changes that Swell has published for a theme, connect to the open-source remote repo (like this one for Origin) and pull in those changes independently rather than pulling them down from your containerized storefront version on GitHub. To push these updates to your theme, utilize the force flag --force (or -f) for best results.

For day-to-day development, we recommend always pulling from our hosted repository to fetch any commits made by our platform before pushing changes to your theme. When pushing your changes, you will need to push back to the master branch with the force flag—designated either as --force or -f. Attaching this flag will override the master branch with your changes.

This process is not necessary if you wish to work with a different codebase—it is specific to working with our dedicated Swell storefront themes.

To initiate a new build in Swell, update the theme’s version number in package.json. We use semantic versioning, so updating the file’s version field will trigger a deploy for your storefront. Additionally, making any other changes (such as dependency updates) to the package.json file will also result in a new build.

For example, changing "version": "2.0.5" to "version": "2.0.6" will trigger a new build.