Updating Customized Shopify Themes

Note: this article specifically deals with updating Shopify themes that predate the Shopify Online Store 2.0 themes. I have amended this post with the process that I use based on Shopify Dawn here.

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 which I’m going to describe in this post.

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. Shopify provides a means to do this easily enough (although it would be great if they published updates with changelogs for their own themes). The first thing that I do when customizing a theme for a customer is to create a ‘change tracking’ theme in the online store’s theme library. This is basically a copy of the theme that the live theme is based off of that will never be customized. This is important to guarantee that this theme in the theme library will always be updated when new upstream versions are released. I also create a copy of this theme in my client source control where I also keep the custom changes that I make to the theme for the client. More on why this is important later.

I then take the version of the theme and rename the live theme to include the version number that it is based off of. You can get the theme version number by clicking ‘customize’ on the theme and then clicking the ‘Theme settings’ tab. Scroll to the bottom of the page to see the theme version. Check back on a regular basis and when you see that version number differ from what’s in the name of your live theme, you know that upstream changes have occurred.

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.

Theme Kit

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:

theme update

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 both of these from the output of the get list command and then use the next command to pull down a local copy of each.

theme get --themeid=[your-theme-id]

If this isn’t the first time that you’re pulling these themes 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).

theme download

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 serves no purpose if you don’t do this.

At this point, you should have three directories locally. One that represents the current state of your live theme, one that represents the current state of the upstream theme that your live theme is based on, and that directory that we said we would discuss later that represents the state of the uncustomized theme that is the same version that your live theme is currently using.

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. You can use a three way merge tool to merge all changes into your live site directory. If you don’t already have a preferred three way merge tool, Meld is a good open source and free option. Having a three way merge is important in order to save time merging files like settings_data.json (which always gets reordered by shopify edits) and to see what’s changed between versions of the theme that your live theme is based on.

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 across all the themes, 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.

Cleaning up

Finally, it’s time to get everything in place to make it easier for the next time you need to do this. Replace everything in the directory that represents the uncustomized theme that your current live theme is based on with the contents of the latest version of the uncustomized theme directory. Don’t copy the config.yml. After doing this, this should be the only file left in the directory that represents the latest version of the uncustomized theme.

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!