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.
Note: Shopify is a hosted platform, and there is currently no truly local development environment option for working with Shopify (such as MAMP, WAMP, etc), making Theme Kit the best option to use your own tooling locally.
Check out Slate for a more robust theme development tool kit, which includes live-reloading, starter themes, and much more.
If you're looking for a purely offline local development tool, check out Motifmate, which has recently introduced an offline option — however, this app is not built or maintained by Shopify.
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.
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
Become a Shopify Partner
Build the customized commerce solutions that your clients need now and in the future. Whether you’re a freelancer or a multi-person agency, working with Shopify will take your business to the next level.Sign up
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]
theme update --version=v1.0.0
To test that Theme Kit is installed and working, type:
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.” 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.
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:
Then, step into that directory using the following command:
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]
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
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.
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 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, 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.
Want to learn more about building themes for Shopify or for your clients?
Check out these additional resources: