3 Simple Steps for Setting Up a Local Shopify Theme Development Environment

Many developers and designers use and love the online Shopify Theme Editor — it’s easy to work with and is conveniently located within the Shopify Admin. But if you’re looking to develop Shopify Themes regularly, you should know that you’re not limited to the online theme editor alone.

In this article, I’ll show you how to install and use Theme Kit — a cross platform tool that allows you to interact easily with the Shopify platform, while using all of your own development tools.

Once Theme Kit is set up, you can more easily integrate workflow tools like Git into your theme development — giving you the confidence to work on a Shopify Theme with a team of developers, work within your favorite text editor, and have a more localized experience when editing themes. Shopify is a hosted platform, and therefore development on Shopify requires a connection to Shopify servers to compile and render Liquid in combination with store data; thus Theme Kit isn't truly local because of this.

Let’s take a look at the process and tools you will use to start building Shopify Themes locally. To get the most out of this article, you will need to know the basics of the command line. You can find additional resources on Codecademy. If you want to ensure that what you're building is secure, be sure to check out our article on website security.

Step 1: Install Theme Kit

Theme Kit is a cross-platform tool command-line for building Shopify Themes, created and maintained by Shopify. 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
• Watch for local changes and upload automatically to Shopify
• Works on Windows, Linux and macOS

If you’re working on Linux or Mac, you can run the following script in terminal to install and set up Theme Kit globally:

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

Alternatively, you can also install Theme Kit manually by downloading a ZIP file on the Theme Kit site. To get up and running, please follow the installation steps provided on the Theme Kit website.

Troubleshooting older versions and testing Theme Kit is installed

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 --version=[version number]

For example:

theme update --version=v1.1.1

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

theme --help

You might also like: The Essential List of Resources for Shopify Theme Development.

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

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.” If you want to work with private apps, then you need to first enable the private app development setting from the “Manage private apps” in admin page. Only the store owner can enable private app development. 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.”

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 ‘mystore.myshopify.com/admin/themes/’. 

Alternatively you can run the following command:

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

This will return to you a list of themes, and their themeid’s that exist on the store specified.

Hooking it all up with config.yml

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 download a specific theme, and create the config.yml file that connects this theme with a local version in the directory you just created, run the following command from inside your theme directory replacing the [square bracket placeholders] with your theme’s information:

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

For example:

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

This will automatically create a config.yml file for you and download the theme from your store (based on the themeid you specified). You can also manually create a config.yml file in the directory with a text editor, which would look something like this:

Creating a theme from scratch

If you want to create a theme from scratch, you can do that by running the following in your command line:

theme new --password=[your-password] --store=[your-store.myshopify.com] --name="New Blank Theme"

This creates a new theme in the directory you run it in, as well as uploads a copy of that theme to your store with the theme name you specified. It also links the two with your theme’s config.yml.

Getting errors?

Did you set the API permissions correctly when you generated your API key? 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.

Did you uninstall the theme gem? Are you using the most up-to-date version of Theme Kit?

Find your new favorite Markdown editor in our roundup.

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 .

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, use Shopify sections, 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.