Most of my Shopify using clients tend to use an existing Shopify theme rather than create an entirely new theme for themselves from scratch. This is a great way to get a store up and running fast. Some use the freely provided themes from Shopify, while others pay to use a special theme created by another Shopify Partner. In either case, if the theme works for the client 100%… things are great! Their Shopify store will automatically update whenever a new version of the theme is available. This however, is rarely the case. There is almost never an instance where even the best theme provides the ability to do exactly what the customer wants to do. This leads to them paying me to customize their theme in order to meet their needs. This is where the problem begins. Once you customize a Shopify theme, you can no longer take advantage of the ability to auto update when a new upstream version of the theme is released. This means, the Shopify store will no longer get security and performance updates, or potentially, the ability to leverage new Shopify features as they are released. After many years of dealing with this issue, I’ve developed a pretty effective way of managing this issue for themes based on Shopify Online Store 1.0 based themes, but in this post, I will cover how to do the same thing with an Online Store 2.0 based theme like Dawn.
Knowing when changes occur
The first step in dealing with this problem is identifying when changes occur upstream in the theme that you’ve customized. With Dawn, Shopify now develops the theme in the open and even provides changelogs. I fork the repository on github and watch for release tag events to alert me that the theme has changed and it’s time to update my client’s themes that are based on Dawn.
Customize the Theme
Before making any changes to a live theme it’s always a good idea to make a backup in case you want to revert your changes. Shopify provides the means to create a backup by going to Online Store -> Themes and in the Live theme section, select Actions -> Duplicate… this will create a copy of the live theme in your Theme Library.
Although you can use the Shopify UI exclusively to customize a theme, this doesn’t really make it easy for multiple developers to work on the same theme or to keep your theme changes in source control. Shopify provides a command line tool, called Theme Kit, that makes both of these things easier. Install Theme Kit before moving onto the next steps.
Before starting any work with Theme Kit, you’ll want to make sure that you’re using the latest version. After installing Theme Kit, you can do this by running:
In order to make sure that you’re running the right Theme Kit commands on the right themes, you need to be able to easily identify your live theme and the other themes in your theme library. This is done using config files. You can always get the theme ids that you use in your config files by running:
theme get --list
Now you need to get a copy of your live theme and the latest version of the upstream theme that your live theme is based on to your local workspace. Identify the theme ids for your live theme from the output of the get list command and then use the next command to pull down a local copy of it.
theme get --themeid=[your-theme-id]
If this isn’t the first time that you’re pulling this theme locally, you can just download the latest using the following command (assuming your config.yml has already been setup and is correct… double check using the output of get –list).
I will often delete everything in the directory except for the config.yml before executing the Theme Kit download command. This is useful because download won’t delete any files that are no longer a part of the theme, so you can end up having extraneous files in the directory that serve no purpose if you don’t do this.
At this point, you should have two directories locally. One that represents the current state of your live theme and one that represents the current state of the upstream theme that your live theme is based on.
Merge in upstream changes
Now it’s time to pull in the upstream changes that have been made to the theme that is the basis for your live theme. If your local fork doesn’t already have the upstream project defined, you’ll need to do that first. If you’re tracking Dawn, it would be like this:
git remote add upstream https://github.com/Shopify/dawn.git
Now, you’ll need to get the latest changes:
git fetch upstream git pull upstream main
You can now merge in all of the upstream changes into your theme. You could use a three way merge tool to merge all changes into your live site directory, but the beauty of everything using git now is that you can use it to manage the process entirely. Identify the git tag that has the tested changes in it that you want to use. The reason for doing this is to ensure that you don’t get any developmental/experimental changes in your live theme. Let’s assume in the following examples, that we want to grab the 2.4.0 release of the Dawn theme. From the git directory that tracks your live theme, execute the following command:
git pull upstream :refs/tags/v2.4.0
Note that this requires that you have your upstream repository set to your fork of the Dawn theme. Also, if your live theme git repository was not created from this repository, you may need to use the following command instead:
git pull upstream :refs/tags/v2.4.0 --allow-unrelated-histories
Now, you’ll need to use your configured merge tool to actually bring the new changes into your live theme.
NOTE: whenever I customize a theme I include a comment to make it clear what I’m changing from the base theme and why. This really helps to jog my memory when doing this merge to decide how the merge should occur and/or if the customization is even still necessary.
After merging all files that have changed, it’s time to push your updated site and make it live!
Push the changes live
First, store all of your live site changes in source control with a nice message that reflects that all of these changes were related to updating to the newer version of the upstream theme that your work is based on.
Now you can publish your live site and test to make sure everything is working correctly. Use the following command from your live site directory:
theme deploy --allow-live
If after testing your site, everything is working great, congrats… you’ve just updated your theme successfully with upstream changes from your theme author. If something went wrong, you can always revert to the backup you made before starting this process and investigate what went wrong.
In Shopify, update the name of the live theme to reflect the version of the base theme that you are now upgraded to. This will allow you to know when to trigger this whole process again. At this point you can also delete any old backups in your theme library that you will have no need of ever reverting to.
Hopefully you found this technique useful. If so, reach out to me in the comments or on social and let me know!