Getting Started with Slater — Bundling and deployment with any existing Shopify Theme

I’m sure some of you are familiar with Slate, the toolkit that Shopify released that powers custom Shopify experiences. It’s a huge awesome step in the right direction and a much better experience than Themekit. Shopify development has improved a lot over the last 5 years, I still remember the days before the API where you were manually creating themes in the editor. :(

Enter Slater

Playing on the notion of Slate, we built our own version of it here at The Couch. Slater is a combination of a number of tools we use internally. What it provides out of the box:

• bare-bones base theme
• JS and CSS compilation via spaghetti
• live reloading
• easy config
• simple CLI

One of the main reasons why we built Slater was to solve a problem we had with the ecosystem of Slate. Slate lacks an eject mechanism, meaning extending the configuration and adding your own libraries (React) is relatively difficult. When I first used Slate I found myself immediately limited by these restrictions. There was no way for me to use NPM, I had no way of configuring my builds and I was basically tied to jQuery. As a result I ended up crafting my own Frankenstein Slate originally that used Webpack and basically only used Slate for the live reloading. I also had no desire to use Sass as we’ve almost entirely adopted the cssnext lifestyle over here.

Adding Slater to your Theme

So obvious next steps here is using Slater. Hop over to our repo and poke around before getting started. Slater by default installs a theme for you when you initialize it, the purpose here is that we want to bootstrap our Shopify development with all the tools we need (listed above). However in this instance we’re going to add it to an existing theme.

Easiest way to get started is to create a new slater instance

slater init new-shopify

This will create our package.json, slater.config.jsand our /src directory. The src directory is just our Shopify theme. We listen to changes in this directory to handle our deployment/compiling.

Copy over your existing theme. We’re basically going to want to just copy all the existing structure of your old theme directly into the new initialized theme. Things to keep in mind, we have some conventions already established in our Styles and Scripts directories. We’ll want to leave those intact to get all the benefits of Slater.

Slater out of the box comes with page transitions. This is a standard that we’ve established internally and as a result we don’t want to rebuild it each time we build a site so it comes out of the box. First let’s get the theme deploying and running and then let’s hook up some of the javascript (or remove some of it that doesn’t apply).

First let’s go into your Shopify Admin. Let’s make a clone of the existing live theme (which should be the same code that you just copied into your Slater init. We’ll use this clone to deploy our initial test instance.

Now in your favorite editor, open up your slater.config.js You’ll see some configurations for development and production here, we’ll want to enter in the theme ID we just created as well as our Shopify store name and API password.

Next let’s configure our initial development deployment:

"deploy:development": "slater build && slater sync --theme development",

Add the above line to your package.json, and then run npm run deploy:development this will deploy our code into our cloned theme. Keep in mind nothing new will be happening just yet. Once the deploy finishes, run npm run start . This will start our live reloading & live deploying of file updates as we develop. But you’ll notice it’s not working because we copy and pasted an existing theme and lost a lot of the default goodies from our starter theme. So let’s add that stuff back in.

Hop into your theme.liquid file and add the following above the body tag:

<script src='{{ 'index.js' | asset_url }}' defer='defer'></script>

Now in Shopify, select your cloned theme (in themes), under actions click preview theme. This will launch your cloned development theme. You should also see an insecure SSL error; this means it’s working. (You will need to accept the insecure exception to enable the reloading) You should now be able to edit files and see them updating in your browser. If you also want to use our css, you can include the following in the head:

{{ 'index.css' | asset_url | stylesheet_tag }}

Page Transitions

Including the javascript snippet above means you’re also getting page transitions out of the box. It also means depending on how your theme is set up, your page navigation might actually be broken out of the box as a result.

In your theme.liquid look for the snippet that has {{content_for_layout}} this will typically have a wrapper div element with an ID. If it doesn’t have an ID add one like root. For example:

<main role="main" id="root">
  {{ content_for_layout }}
</main>

This will make page transitions work, if you already have an ID, simply copy and paste it, and hop into our scripts/index.js which is our root JS file. You’ll see our router configured here that handles the page transitions. It defaults to root so you can just update it to whatever the ID is in your theme.

If you included our CSS you’ll see an is-transition adding some basic transitions. If you did not, you’ll want to add a is-transitioning class to the body, for example:

.site-overlay {
  background: var(--theme);
  position: fixed;
  z-index: 200;
  top: 0; bottom: 0; left: 0; right: 0;
  height: 100vh;
  transform: translateY(100%);
  transition: transform 300ms var(--cubic);
body.is-transitioning & {
    transform: translateY(0);
  }
}

Then in your theme.liquid add the follow below the <main> div we referenced above:

<div id='siteOverlay' class='site-overlay'></div>

You may need to edit the z-index in the css depending on the structure of your existing theme.

You now have a working version of Slater in your theme!

Keep in mind depending on how your javascript is setup our page transitions may not work out of the box for you (you’ll need to reinit your js on transitions).

The Javascript

There’s a decent amount of javascript in our little starter. This is very much still in progress, and if you have contributors feel free to make a PR. We also wrap all of our Javascript with picoapp, this is a really light weight lib that lets us compartmentalize our JS and do some component mapping as well as mount and unmount it (this is really important for handling the ajax page transitions and still handling our javascript initialization).

You’ll also notice there’s no jQuery ;). If the JS isn’t for you, you can simply comment out the content of the index.js file, but keep the css import as you need that for live reloading styles!

Resources:

the-couch/slater

Mega extra kudos to Eric for all his work on this project!

~Cheers

Update: Slate has been moved to low maintenance mode. So anyone hoping to continue with some modern Shopify development tools, feel free to contribute and PR! :)