Getting Started with Slate in 4 Simple Steps

Getting Started with Slate in 4 Simple Steps

Getting started with Slate in 4 simple steps

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

Install Node.js

To install Slate you’ll first need Node.js and npm installed on your computer. This is because Slate is an npm package.

Node.js automatically ships with npm, so you’ll need to download and install Node v.6.11.0 LTS. Follow installation instructions found on the Node.js website.

To see if you have node already installed, check the version run:

node -v

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.

Install Slate

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.

Getting started with Slate in 4 simple steps - Installing 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]

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

Getting started with Slate in 4 simple steps - Creating a new theme with Slate

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 [theme-name]

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

slate zip

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.

Rename config-sample.yml

First, rename config-sample.yml — found in the main directory of your project — to config.yml.

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.

password

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 config.yml file.

theme_id

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.

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

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 build, 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!

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