Shopify Theme Kit

Step 1: Install Theme Kit

Theme Kit is a cross-platform tool for building Shopify Themes, created by Shopify employees. Theme Kit is a single binary that has no dependencies. Once you download Theme Kit, and with a tiny bit of setup, you’re off to the theme-creation races.

Some of Theme Kit’s notable features include:

Uploading themes to multiple environments.
Fast uploads and downloads.
The ability to watch for local changes and upload automatically to Shopify.
Works on Windows, Linux and macOS.

Linux or Mac instructions - you can run the following script in terminal to install and setup Theme Kit globally:

curl -s https://raw.githubusercontent.com/Shopify/themekit/master/scripts/install | sudo python

!> I'm skipping windows instructions but you can find them here if you need them.

theme kit 1

Step 2: Setting up API credentials

Once Theme Kit is installed, we’ll need a few things to connect our local theme to your existing Shopify store. We’ll need an API key, password, and theme ID.

API Key and password

?> If you don't see an apps link in the left sidebar we may need to request more permissions from the store owner. Or ask them to setup a private app for us and provide us with the necessary info.

We’ll need to set up an API key to add to our configuration and create a connection between our store and Theme Kit. The API key allows Theme Kit to talk to and access your store, as well as its theme files.

To do so, we need to log into the Shopify store, and create a private app. In the Shopify Admin, go to “Apps” and click on “Manage private apps.” From there, click “Create a new private app.” You’ll need to provide a title — I usually provide the name of the client and environment for clarity. Make sure to set the permissions of “Theme templates and theme assets” to have “Read and write access” in order to generate the appropriate API credentials, then click “Save.”

private app

Shopify will load a new page, which will provide you with a unique API key and password.

Theme ID

To connect an existing theme, we need the theme’s ID number. There are a few ways to get your theme’s ID number, but I find the quickest way is to go to the Theme Editor click on Edit HTML/CSS and copy the theme ID number from the URL — it will be last several digits after

store-name.myshopify.com/admin/themes.

theme kit 2

Creating a config.yml file

Now we can use all the previous information to create a config.yml file in our theme, and then download the whole theme locally. The config.yml is vital because it’s the file that creates a local connection to your Shopify store’s theme.

Create a directory for your theme to live in, by running:

mkdir [your-theme-name]

Then, step into that directory using the following command:

cd [your-theme-name]

To create the config.yml file, run the following command from inside your theme directory replacing the [square bracket placeholders] with your theme’s information:

theme configure --password=[your-password] --store=[your-store.myshopify.com] --themeid=[your-theme-id]

For example:

theme configure --password=01464d4e02a45f60a23193ffc3a8c1b3 --store=the-soap-store.myshopify.com --themeid=170199178

This will automatically create a config.yml file for you. You can also manually create a config.yml file in the directory with a text editor, which would look something like this:

development:
  password: 98c36118fde68d0cda093056894b76c0
  theme_id: "37586501719"
  store: store-name.com

Then you can run the following command to download and setup your existing theme in the current directory:

theme download

Step 3: Push updates to your theme

Now that the connection has been established to the Shopify Theme, you can run the following command in your theme directory:

theme watch

Theme Kit will now watch for any changes made to your local files, and automatically push them to your theme. To close the watch connection, simply type ctrl + c .

theme kit 3

That’s it! You’ve set up Theme Kit

That’s all there is to it! Now you can more easily track your code with version control, work with a team of developers, use you favorite text editor, set up shortcuts, and pretty much anything else you would normally do when building locally.

If you’re looking for more reading on using Theme Kit, check out the extensive documentation and other amazing features.

Troubleshooting

Before you run any Theme Kit commands, make sure you are using the most up-to-date version of Theme Kit, and have uninstalled the theme gem if you have used it previously. If it’s your first time installing Theme Kit, you can ignore the following instructions.

Uninstall existing instances of the shopify-theme gem if you have with the following command:

gem uninstall shopify-theme

Make sure you are using the most up-to-date version of themekit (you can find versions here). To update Theme Kit run:

theme update

To test that Theme Kit is installed and working and see available commands, type:

theme --help