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 itself. But if you’re looking to develop Shopify Themes locally, 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 setup, 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, therefore Theme Kit isn't a truly local development environment, because it requires a connection to Shopify servers. Currently, there is 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. If you're looking for a purely offline local development tool, checkout Motifmate, which has recently introduced an offline option — just note that 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.
You might also like: The Essential List of Resources for Shopify Theme Development.
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.
If you’re working on Linux or Mac, 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
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:
To test that Theme Kit is installed and working and see available commands, type:
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 View private apps. From there, click Generate API credentials to create your 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
If you want to bootstrap a theme from scratch, you can do that by running the following in your command line, which creates a new theme from the Timber template in the directory you run it in:
theme bootstrap --password=[your-password] --store=[your-store.myshopify.com]
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 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]
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:
Then you can run the following command to download and setup your existing theme in the current directory:
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.
You might also like: The 7 Best Free Shopify Resources and Tools for Front-End Developers.
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:
Have any questions about developing Shopify Themes locally? Feel free to include them in the comments below.
***Content updated March 2017