Local Shopify Theme Development with Theme Kit

Theme Kit is an integral part of Shopify theme development.

Theme Kit is a command line tool for Shopify themes.

Using Theme Kit will enable you to

  • Upload Themes to Multiple Environments
  • Fast Uploads and Downloads
  • Watch for local changes and upload automatically to Shopify
  • Works on Windows, Linux and macOS

Using Visual Studio Code (from the previous lesson), we can bring up the terminal within our editor. For macOS users, it's as easy as clicking the top menu item Terminal > New Terminal. For Windows, it is a bit more steps, follow the stackoverflow answer here to get your command line working. It will appear on the bottom right of the application.

 Visual Studio code with open terminal

If you ever close or minimize the terminal, you can reach it again by clicking the small icons on the bottom left, under the settings gear icon. This will bring up the layout the terminal was in, but you will have to click the three icon tab and choose "Terminal". 

Opening terminal on Visual Studio Code

Now that we have the terminal working we can start on the installation of Theme Kit. 

For macOS users, download and install homebrew, then run two commands:

brew tap shopify/shopify , then brew install themekit.

For Windows users, download and install chocolately and run command:

choco install themekit

For Linux users, you can download and install the latest Theme Kit using this command:

curl -s https://shopify.github.io/themekit/scripts/install.py | sudo python

On your web browser go to your store and login. On the left sidebar click "Apps". Then on the bottom of the page, click "Manage private apps".

Manage private apps link on Apps page

There might be a notice of "Private apps are currently disabled", click the button "Enable private app development". 

Private apps are currently disabled

Then accept all the changes and click "Enable private app development" button again.

enable private app development form

This will redirect you to the private apps page, click "Create private app" button. 

create private apps for your shop

 This will bring you to a "Create private app" form. In the "App details" type in the "Private app name" field with "Theme Kit" and use your email for the "Emergency developer email".

Private app details

Then in the "Admin API" section, click "Show inactive Admin API permissions" to view a list of API permissions you can give.

Admin API section

When you open the list of permissions, scroll down until you find "Themes" and choose "Read and write". Make sure other permissions are under the "No access" option. 

Theme with Read and write access

Then click save on the bottom or the top of the page. A confirmation popup will appear, click the "Create app" button.

Create private app confirmation popup

You will be redirected to your app detail page. Here you can see newly generated API key and password. 

Admin API key and password

Keep this page open as we will need to copy the API password later. Now we will have to add a config file to our theme folder. Go back to your code editor and add a new file to your project. You can either go to the menu "File > New File", right click the project then select "New File", or click the file plus icon to add a new file.

Visual Studio Code add new file - config.yml

Make sure the config.yml file is in the root of our theme folder. Inside that file we will add the configuration variables: api password, store url, and theme id. To find the theme id we will use the newly installed command line tool. Go to your terminal add run this command.

theme get --list -p=[your-api-password] -s=[your-store.myshopify.com]

Use your own password and store url. My command will look like this.

theme get --list -p=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 -s=development-joepichardo.myshopify.com

After running the command you should see a list of theme ids in your terminal:

Available theme versions:
  [113126244502] Debut
  [113209671830][live] Bare-minimum-shopify-theme-by-joe-pichardo

Copy the theme id for the "Bare Minimum Shopify Theme" we uploaded in an earlier lesson. My id here is 113209671830. Now we have all the variables needed for our config.yml file. Here is an example of the contents I have in mine.

development:
  password: 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
  theme_id: 113209671830
  store: development-joepichardo.myshopify.com

# Windows	%APPDATA%\Shopify\Themekit\variables
# Linux/BSDs	${XDG_CONFIG_HOME}/Shopify/Themekit/variables
# MacOSX	${HOME}/Library/Application Support/Shopify/Themekit/variables
# Any	--vars flag provides a path to a file for loading variables
# file to load ignore patterns, check out the ignore file example

As you notice, there is some extra details on the bottom of the file. This is for if you want to use environment variables instead of hardcoding your security details in your project file. This is a best practice you should get used to. The file paths are the specific files you need to create and will be used to automatically add your configuration variables. My "variables" file contents look like this:

teststore_DEV_PASSWD=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
teststore_DEV_THEMEID=113209671830
teststore_DEV_SHOP=development-joepichardo.myshopify.com

Now we can change our config.yml file to include the environment variables.

development:
  password: ${teststore_DEV_PASSWD}
  theme_id: ${teststore_DEV_THEMEID}
  store: ${teststore_DEV_SHOP}

# Windows	%APPDATA%\Shopify\Themekit\variables
# Linux/BSDs	${XDG_CONFIG_HOME}/Shopify/Themekit/variables
# MacOSX	${HOME}/Library/Application Support/Shopify/Themekit/variables
# Any	--vars flag provides a path to a file for loading variables
# file to load ignore patterns, check out the ignore file example

Now we can start running Theme Kit commands to automatically upload our Shopify theme files. Use this next command to watch when your files are saved so they can be uploaded.

theme watch --allow-live

We are using the tag "--allow-live" to deploy the file changes to the currently live theme, since our theme is the active published theme. Now we can see in the terminal that our command is running. Add a change to the "theme.liquid" file and save. You should see "processing" and "Updated" output in your terminal for the files you've changed.

Testing theme watch files command

If we go to our store's front page, we can see the newly saved change. As you can see in the previous image, I added an h2 tag with "Testing theme watch" and this appears on our homepage. 

Website change from theme watch test command 

Finally! We can now start tinkering with Liquid code. Yes, it took a few steps to set up, but now we know the foundations of working with Shopify theme files. We can implement what we learned to any stores we work with. We are prepared for success in learning Liquid. Next, are the basics of the Liquid templating language.  

 

Joe Pichardo | Shopify Developer

About Joe Pichardo

Joe Pichardo is a Shopify Developer creating themes and apps to help other programmers succeed on the ecommerce platform.