Working With an IDE, GitHub and Shopify – Setup

If you’re intending to develop or extend a theme within Shopify. You need some kind of version control. In truth no software project of any size should be without version control. One of the most popular version controls is Git – frequently run from GitHub. Here’s a quick guide to setting up GitHub and Shopify to work together.

… and because editing in a browser window is horrible, we’ll also tell you how to set up your project in an IDE.

These instructions are written for MacOs users but the processes and software exist for Windows.

Version control software monitors and records changes to files within a project. It facilitates coordination, sharing, and collaboration across the entire software development team. Version control enables teams to work in distributed and asynchronous environments, manage changes and versions of code and artefacts, and resolve merge conflicts and related issues.

Git is a free, open source version control tool that developers install locally on their personal computers, while GitHub is a pay-for-use online service built to run Git in the cloud.

Just another TLA of course! Seriously though, integrated development environment (IDE) is a software application that helps programmers develop software code efficiently. It increases developer productivity by combining software editing, building, testing and packaging capabilities in an easy-to-use application. Just as writers use text editors and accountants use spreadsheets, software developers use IDEs to make their job easier.

Shopify offers tight integration with Git version control and codecs exist to make Liquid environments work seamlessly within Microsoft software.

There are command-line (CLI) tools for managing Shopify themes but most, if not all, of the advantages offered by those solutions can be better achieved in conjunction with desktop software solutions. Desktop solutions also offer the following advantages:

• At the time of writing (June 2022) IDE software does not care about the templating version used. Whereas two different suites of CLI tools are recommended for managing Shopify 1 or Shopify 2 template versions.
• The operative can gain most of the benefits of the CLI tools whilst remaining in their native desktop environment.
• Because of the code branching tools offered by Git, development branches can be added to Shopify as development themes and previewed with live data using the excellent Preview Theme tool.

This document assumes the user has an active GutHub account and permissions to access relevant projects.

Preparing a Shopify Theme for Use with GitHub

Given the enormous advantages of developing a Shopify theme with version control, no theme should be developed without it. Where a theme already exists, it should be imported into Shopify before further work is undertaken on it.

NOTE: several activities on the website itself (for example, adding blog posts) can change the contents of a theme’s files. When creating the repository to contain the theme and importing that back into Shopify, the website should be embargoed for the duration of the operation.

Download the Theme

From the Online Store landing page within Shopify, locate the theme with which you wish to work and download the theme file as illustrated.

Shopify will email you a link to the files for you to download. While you are waiting, create an empty Git repository from which the theme files will be managed.

Creating a Local Repository

Go to GitHub Desktop and select Create New Repository as illustrated.

You will be led to the following dialogue:

Enter appropriate values and click Create Repository.

Adding Theme Files to the Local Repository

By now you should have received a link from Shopify with a link to download your theme files. Download the files and copy them to the Local Path (repository directory) chosen when creating the repository.

The changes to your local directory will be monitored by Git. Git maintains a record of these changes to your local files. This is called your Local Repository. When you are happy with the changes made in your files (e.g. your work is complete) you can commit your changes to your Local Repository. You will be asked to explain the purpose of your changes for the version log.

Fetching from your online repository (GitHub) will update your Local Repository and potentially make changes to the files in your local directory.

Pushing from your Local Repository will update GitHub and change the contents of the files online.

Important

The repository directory contains important hidden files. Do not overwrite the directory. The directories in the root of the zip (assets, config etc.) file must also be in the root of the repository directory, thus:

Note – hidden files are displayed in the above view. The items .git and .gitattributes must not be moved or manually altered or the repository will break catastrophically.

Once copied, your GitHub application will list the changed or new files (all of them). Add a summary (e.g. ‘Initial Import’) and a description and commit your changes.

Publishing your Local Repository to GitHub

Once the files are copied, your GitHub application will invite you to Push Origin to GitHub, do so. It will take a few minutes to complete the creation of your GitHub online repository and transfer the files.

Once complete, you are ready to import your GitHub-controlled theme into Shopify.

Importing Your New Repository to Shopify

Return to Shopify and locate the Online Store page. Your Theme Library is in the bottom half of the landing page.

Select the Connect from GitHib option from the Add theme selector.

If you haven’t already you will be asked to log into GitHub from Shopify. Once complete, a dialogue will appear on the right-hand side of your browser screen from which you can select the repository you have just created.

You will be asked to connect to the branch with which you wish to work. At this point there will only be the main branch. Click the Connect button next to your branch name. Your repository will now appear in your Template Library as a theme.

This theme is just like any other in Shopify, it can now be published to live (indeed it should be before the live website and the GitHub repository diverge).

Working With a GitHub-Connected Theme

Once imported, it is best to make future changes to the theme code in a suitable desktop IDE. It is vital to note that this theme is directly connected to GitHub, changes made to this theme’s code editor within Shopify will be applied directly to your GitHub online repository.  No comment will be requested (though a log entry is added).

Some changes (e.g. theme settings) and blog entries affect the files in the theme itself. These will, in turn, affect the GitHub repository. These changes will be imported as you Fetch Origin when working on your theme.

Working With a Branch

Branches allow you to make changes to your code without affecting the base code. Since the main branch is likely to be your live code, this is essential, development can involve a lot of trial and error. 

Git also offers tools that help integrate your changes back into the Main branch, minimising the risks when working multiple teams on the same code base.

In your desktop application, create a new branch.

Once created, Publish the new branch to GitHub and return to Shopify. From the Theme library section select Connect from Github again. The dialogue will appear on the right again, navigate to your repository and your new branch will be available to add.

Click Connect and your new branch will now appear in Shopify as a theme.

Once development on this branched theme is compete and tested, Git Pull Requests can be made to make the Main branch (which is the published theme) reflect the changes made in the branch.

Preparing up a Macos desktop to work with Shopify, VScode and GitHub

Microsoft offer tight integration with Liquid and Shopify. PHP Storm, another excellent IDE, also supports Liquid editing.

To work with an integrated Shopify/GitHub environment, the following software needs to be installed.

• Shopify CLI for themes – https://shopify.dev/themes/tools/cli – this should be installed before visual studio
• Microsoft Visual Studio for Mac https://code.visualstudio.com/
• GitHub Desktop for Mac – https://desktop.github.com/

Once Visual Studio is installed, open the software and head to the Extensions Preferences.

Search for the official Shopify Liquid extension and install it.

Once installed, go to the File menu, open any folder containing a local set of theme files and start work.

Whilst many tools in GitHub have their equivalents in Visual Studio, the simplicity of GitHub Desktop and the explicit nature of the actions make it the preferred choice for Git operations.