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

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 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

Local Shopify Theme Development Environment: Theme KitTheme 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

Local Shopify Theme Development Environment: Theme Kit 2Alternatively, you can also install Theme Kit via Homebrew, or the Windows Installer. 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

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

theme --help

Step 2: Setting up API credentials

Local Shopify Theme Development Environment: API CredentialsOnce 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.

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/.

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:

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:Local Shopify Theme Development Environment: Config.yml

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

theme download

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?

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 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, 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.

Have any questions about developing Shopify Themes locally? Feel free to include them in the comments below.

***Content updated March 2017

About the Author

Tiffany is a Front End Developer Advocate Lead at Shopify. She specializes in front end development, user experience design, accessibility, and is passionate about inspiring young designers and developers. Previously, she was an Ottawa Chapter Lead for Ladies Learning Code and worked as a Front End Developer for Partnerships at Shopify.

Grow your business with the Shopify Partner Program

Learn more