How to Develop a Shopify Theme

9 November 2018 / Ecommerce

Are you a developer new to Shopify theme development? In this article, I'll explain briefly how Shopify works, how to install Slate and Theme Kit, how to start using Liquid to edit Shopify templates, as well as cover tips and tricks to help in your Shopify development journey.

Background

Shopify is a SaaS ecommerce platform similar to Magento or WooCommerce. Unlike its open source competitors, it's offered as a hosted solution only. But this plays into Shopify's strengths, allowing you to focus on the store experience while Shopify is taking care of the server backend. In addition to providing a robust set of features, Shopify is easy to use and manage even for non-technical users.

Shopify pricing has three tiers, but the most important distinction is normal Shopify versus Shopify Plus. Plus is the enterprise version of Shopify that unlocks a number of features, but most relevant for theme development is the ability to edit the checkout page template.

Getting Started

The first step in developing a Shopify theme is to decide whether you will start from scratch or use an existing theme. The former will give you more flexibility to add new features, while the latter will decrease your development time at the cost of customizability. You can find free and premium Shopify themes here.

Once you've decided whether to start new or use an existing theme, you can move on to deciding which tool you'll use. It's important to know that you cannot run Shopify on a local machine. Instead, changes will be previewed on an online development store, and you will rely on either Slate or Theme Kit to upload your changes automatically to Shopify.

Slate vs Theme Kit

Theme Kit is a command-line tool that provides commands for uploading, downloading, and updating themes to Shopify stores. Slate, on the other hand, is an opinionated toolkit that provides a modern development workflow. Theme Kit is a good option if you're using an existing theme, if you're creating your own development workflow, or if you're interested in keeping your workflow simple (no minifying, no transpiling, etc.).

As of November 2018, Slate v1 hasn't been certified for Windows, but I can confirm that it works, although the setup takes much longer than Theme Kit.

In this guide, I'll cover both tools and let you decide which is better for your use case.

Creating an API Key

Before we can use these tools, we must first create an API key. Log in to your store and click on Apps on the left menu. Click on Manage private apps and select Create a new private app. You can name it however you like. For permissions, make sure you select Read and write for everything, including for Theme templates and theme assets. Once you're done, hit Save. Scroll down to find your API key and password. You will use this for Theme Kit or Slate.

Option 1: Setting Up Slate

Slate requires either npm or yawn. I recommend using npm. If you don't have it installed, you can download npm/nodejs here.

To create a new theme, issue the following command:

npx create-slate-theme <your_theme_name>

npx will take care of installing the create-slate-theme package.

Inside your newly created theme, open .env and paste your corresponding values:

  • SLATE_STORE is the URL of your store.
  • SLATE_PASSWORD is the password found in your private app.
  • SLATE_THEME_ID is the ID of the theme in your store. It is unique to your store, so it can change if you're connecting to another store with the same theme. Your store comes pre-bundled with three themes that you can use. To find the theme IDs, open https://{your-store}.myshopify.com/admin/themes.xml. This will overwrite the existing theme.

Slate Part 2: Creating a Self-Signed SSL Cert

Let's create an SSL certificate that Slate will use to serve assets.

Install mkcert:

Windows:

Make sure that you have git bash installed first.

choco install mkcert

Note: If you don't have Chocolatey installed, head over to https://chocolatey.org.

Afterwards, run:

mkcert -install

macOS/Linux:

macOS:

brew install mkcert

Linux:

sudo apt install libnss3-tools

After you've installed mkcert on your OS, we'll need to run a script to create the SSL certificate.

Windows:

Download this script and run it using git bash:

wget https://gist.githubusercontent.com/mfigueroa/90f4d256921c3d8923101198a1ad2f89/raw/0dbe3f5c2dde8ec0b890332509c873c9fbbb5396/ssl-check-windows
./ssl-check-windows

macOS/Linux:

Download this script and run it on your terminal:

wget https://gist.githubusercontent.com/mfigueroa/3a0061abaf5d7272daa4954f776f8439/raw/64488010e491cce6fb6c24c6828f3b8746f43ccd/ssl-check-linux-macos
chmod +x /ssl-check-linux-macos
./ssl-check-linux-macos

That's it! Enter yarn start to run Slate.

Option 2: Setting up Theme Kit

Open up a terminal and run your corresponding command:

Windows (Run Powershell as Administrator):

(New-Object System.Net.WebClient).DownloadString("https://raw.githubusercontent.com/Shopify/themekit/master/scripts/install.ps1") | powershell -command -

macOS/Linux:

curl -s https://raw.githubusercontent.com/Shopify/themekit/master/scripts/install | sudo python

Once you've installed Theme Kit, open a new terminal and create a new folder. Create a new file called config.yml and add the following:

development:
    password: YOUR_API_PASSWORD
    theme_id: YOUR_THEME_ID
    store: YOUR_STORE_NAME.myshopify.com

If you don't know your theme ID, you can leave it blank for now. Set your password to the API password that you created previously.

That's it for setting up Theme Kit!

Starting from an Existing Theme

If you're starting from an existing theme, run the following command:

theme get --list

You will see something like this:

Available theme versions:
[34931310665][live] Debut
[34931638345] Boundless
[34960834633] Boundless

Select the theme ID that you're starting off from and place it in config.yml.

Starting from Scratch

If you're starting from scratch, you can create a new theme with the following command:

theme new

Publishing Your Theme

When you're actively developing your theme, use the following command to automatically push your changes:

theme watch

If you wanted to upload your entire theme, use:

theme deploy

Diving into Liquid

Liquid is the frontend template language developed by Shopify. It's conceptionally similar to other template languages such as Handlebar or Laravel's Blade. Before we dive into creating a template, let's discuss the main pieces that makes up a Shopify theme.

Structure of a Shopify Theme

A Shopify theme is divided into 7 directories:

  • assets: every non-template file, such as images, CSS, and JS.
  • config: theme customizations
  • layout: the main layout templates; every Liquid template file is based off one of these layouts
  • locales: internationalization files
  • sections: the major parts of a template, such as the header and footer
  • snippets: template snippets
  • templates: template files that correspond to a page

Templates

Every file inside the templates folder maps directly to a URL path in a Shopify store as follows:

  • 404.liquid: /404
  • article.liquid: /blog/{blog-article}
  • blog.liquid: /blog
  • cart.liquid: /cart
  • collection.liquid: /collection/{collection}
  • index.liquid: /index or /
  • list-collections.liquid: /collections and /products
  • product.liquid: /product/{product}

Now that we have a general idea of where the store's content lives, let's edit a Liquid template.

Editing the Home Template

The homepage of a Shopify store lives on templates/index.liquid.

This template uses layout/theme.liquid as its container. If I wanted to make a change that would carry across the entire website, I would edit theme.liquid, since every file in the templates folder shares this layout.

Let's say I have a sign up form that I want to include in the homepage. I create it as a snippet under snippets/newsletter.liquid, and add the following tag inside index.liquid:

{% include 'newsletter.liquid %}

To include a stylesheet, save the file as style.scss in assets and use the asset_url and stylesheet_tag tags. Notice how I chain them (from left to right) using the pipe character:

{{ 'style.scss' | asset_url | stylesheet_tag }}

Adding Images

To include an image, save it in your assets folder and reference it on your template as follows:

{{ 'name_of_image.png' | asset_url }}

asset_url is a URL filter that outputs a link to Shopify's CDN.

Note: Folders inside the asset folders are not accessible through the CDN.

There's another URL filter called asset_img_url that lets you control the width and height of the CDN image:

{{ 'image.png' | asset_img_url: '300x' }}
{{ 'image.png' | asset_img_url: '300x200' }}

To include an asset image inside a CSS/SASS file, simply refer to the image filename in the assets folder, e.g. background: url(bg-footer.png).

Editing the Product Template

The product template is responsible for pulling the product attributes defined in the Shopify admin dashboard.

Inside the product.liquid template, you have access to the product object. The product object contains every field for the product being requested. Some of the most important fields include:

  • product.id
  • product.images
  • product.title
  • product.description
  • product.price

For a full list of attributes, see the product object reference.

Product Images

The product.images attribute is an array of product images defined by the store administrator. Each item is an image object that contains attributes such as width, height, alt, and src.

Metafields

Every product has a standard set of properties that is defined in the Products backend. However, there is an additional set of properties called metafields that are not normally available in the admin dashboard. Metafields allow you to define custom properties for your products, but you must rely on an app to add and edit them.

Let's say you want to create a metafield for YouTube videos. With a metafield app, you can define the videos as custom fields and include them in your product template.

Tips and Tricks

Accessing an Element in an Array

This is one of those things that's not documented in the Liquid documentation. To retrieve the first element of an array, use array.[0].

Getting the User's Cart

To retrieve a user's current cart, perform a GET request on /cart.js. The starter themes such as Boundless have a cart API that wraps these endpoints, but if you plan on creating custom features, you'll need to query the cart. Learn more about the cart AJAX API here.

Checkout Cart

This JSON contains all the cart item information in JSON format: https://{your-store}.myshopify.com/cart.js

Theme Hacking: Custom Endpoints

What if you needed to retrieve metafields for cart products using AJAX? The /cart.js endpoint doesn't provide product metafields. However, you can create your own endpoint, similar to cart.js, and pull every metafield that you need by iterating through the cart.items object.

Create a file called templates/cart.CUSTOM_NAME.json.liquid. This Liquid template will map to the URL /cart?view=CUSTOM_NAME.json. Define the contents as follows:

{%- layout none -%}
[
{% for item in cart.items %}
    {
        "metafield1": {{ item.metafield1 }}
    }{% unless forloop.last %},{% endunless %}
{% endfor %}
]

You then perform a GET request on /cart?view=upsell.json and parse the response with JSON.stringify(). You can get creative and customize it to fit your needs.

Additional Resources

Liquid has hundreds of tags and objects that can't be covered in one article. But you should now have a good idea on how to start your Shopify development.

To learn more about Liquid, I recommend reading the Liquid Reference whenever you have a specific question. You should also rely on the Shopify Cheatsheet to find quickly find tags and filters.

Beyond Liquid, Shopify provides additional libraries and APIs for specific use cases. For example, the Shopify Ajax API allows you to build an interactive cart. Head over to Shopify's Github to learn more.

Manuel Figueroa

Full Stack Developer

Thank you for reading my blog. Please feel free to contact me or read my other content.

Manuel Figueroa