Slate is a front end framework for building Shopify themes. With Slate you can build themes using modern tooling and the command line, making the development process faster for theme developers. If you’re looking to learn more about the benefits and features of Slate, you can check out the webinar I hosted with Nathan Ferguson, as well as a blog post I wrote introducing Slate.
Slate is both a theme scaffold and a set of command line tools, which help you build custom themes for Shopify. This article will cover how to install Slate, create a new theme, and connect that theme to a Shopify store. To follow along, you should have a basic understanding of the command line / terminal. If you haven’t used the command line before, checkout this great tutorial on command line basics.
You might also like: Introducing Slate: A Shopify Theme Scaffold and Command Line Tool.
1. Installing Node.js and Slate
To install Slate you’ll first need Node.js and npm installed on your computer. This is because Slate is an npm package.
To see if you have node already installed, check the version run:
Slate will run on v.4 and higher, however if you have the most current version of Node.js on your computer (v.8), which is higher than v.6.11.0 LTS, you’ll want to downgrade your node version. At the time of writing this, there are a few known issues with Slate and Node v.8 due to some third-party package dependencies, which have not yet been updated to work with v.8.
To install Slate you’ll need to run the following command from any directory, via the command line or terminal app on your computer:
npm install -g @shopify/slate
When you run this command the
-g specifies that you’re installing Slate globally on your machine, which means it will work in any directory. If you run into any issues, troubleshoot by checking your Node.js and npm versions, and making sure they’re the appropriate versions to run Slate.
2. Create a new theme
The next thing you need to do is create a new scaffold theme using Slate. To do this, simply run the following command from the directory you’d like your project folder to reside in:
slate theme [theme-name]
[theme-name] will be the name of your newly created theme/project folder. Make sure not to include spaces in your theme name, if you do, the first word in the theme name will become your new theme directory, and any additional words will be ignored.
The command should read something like this, where my-custom-theme is the name of the newly created directory:
slate theme my-custom-theme
3. Upload your theme to your client’s Shopify store
The next thing you need to do is get your newly created theme into your client’s store. To do this, you’ll need to run a command from inside your local theme directory. To navigate into your theme directory, type this from the command line:
cd command stands for “change directory”, and will take you inside whichever directory path you specify after it. Once inside the theme directory, you can run:
This will build and compress a
dist/ directory into a zip file for easy manual upload to your client’s store. Once run, you’ll see a
upload/ directory in your project, containing your zipped theme. There currently isn’t a command to deploy a local theme to a store, without first connecting it to an existing
theme_id. To create that
theme_id for a brand new theme, without overwriting an existing one, you need to upload your newly created theme.
From the Shopify Admin, go to Online store > Themes, and then click Upload theme to upload your newly created zip file. Make sure to click Publish theme, once it’s been uploaded to your store.
4. Connect your store to your local version
Now that you’ve uploaded your Shopify theme made with Slate, you’ll be able to connect the local version to the one that you’ve uploaded.
config-sample.yml — found in the main directory of your project — to
Then, add your store information and private app credentials to the appropriate environment. In this case, we’re creating a development store, so I would edit the
development credentials, and remove
production for now.
To get a
password, we’ll need to set up an API key to add to our
config.yml, creating a connection between your client’s store and your local theme.
To do this, you need to 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 a 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 the
password you need for your
This is the unique id for the theme you want to write to when deploying to this store. You can find this information in the URL of the theme’s online editor at Shopify admin/themes, and click on the
… > Edit HTML & CSS link for the published theme. The
theme_id is found at the end of the URL. Alternatively, you can use
live as shorthand to select whichever theme happens to be the currently published in your store.
This is the Shopify-specific URL for this store/environment (ie. my-dev-store.myshopify.com) that you are trying to connect to with your client’s local theme.
You might also like: Simple Steps for Setting Up a Local Shopify Theme Development Environment.
Common gotcha’s and things to keep in mind
When developing with a new tool, there's always a few things that can go wrong. Here are a few things to keep in mind when starting your next project with Slate.
Be careful with
When developing with Slate, there are a few commands that you should fully understand before using. One of those commands is
slate start, which runs the
slate deploy, and
slate watch to get you developing quickly. However, because it runs all three commands, if you’ve made changes to your client’s store, which updates theme settings, and you haven’t saved those locally or synced them locally, your local version can potentially wipe out those settings.
It’s important to consider what files have changed on your client’s store and do not exist in a local version of your theme, before you run
slate start. There’s currently an open issue for this concern on GitHub; you can follow the discussion there if you’re interested in the workflow to avoid this from happening.
You might also like: The Essential List of Resources for Shopify Theme Development.
Importing additional stylesheets and third party libraries
When importing additional stylesheets in
theme.scss, it’s important to note that the
import statements found in Slates’
theme.scss, are not actually Sass import statements. Rather, these
imports build your stylesheet only when running slate commands, and they require a build script to compile properly.
To add additional Sass files, simply create new files in the appropriate directory within the
styles folder, and add a new import line for the newly created file with the correct path. You should then be able to run
slate watch, and see your changes reflected.
If you intend to use a third party library, you should know that the Sass in Slate is actually rendered by the Shopify servers, and Shopify currently supports Sass version 3.2. For a longer explanation about why Shopify is using an older version, read an Introduction to Sass with Shopify (towards the end of the article).
At the time of writing this article, there are a few issues with specific third party libraries; these mostly have to do with file size and timeouts. There are, however, recommendations on troubleshooting these issues, which can be found in the GitHub discussion linked above, I highly recommend reading if you want to use Foundation or Materialize as a base.
Have you started using Slate already? Let us know in the comments below!