A beginner’s guide to Shopify Themekit and Schema

I began to learn to code during lockdown in 2020 and since then I have relied on the kindness of strangers to share their own solutions, insights, and hacks when I get stuck. Now in my first dev job, I find not much has changed, and googling specific error messages is synonymous with “engineering”. While Shopify has a lot of information for developers, in my experience their documentation is verbose to the point of redundancy. Why are there so many different pages, and no examples? In the spirit of paying it forward, I’d like to share some of the guidance that I would have liked when I began front end development using Shopify Themekit.

Themekit allows you to duplicate your website’s existing design into an unpublished version that you can modify without affecting the deployed version visible to your clients. Rather than pushing your changes to Github, with commands like $ themewatch you can see your updates in real time*.

*Web development through Themekit still requires hard reloads of your page to see changes, but this is still less steps than pushing your changes to a repo manually.

Part 1 — Setting up Themekit in your local environment

I used Homebrew to set up themes on my local environment with these commands:

$ brew tap shopify/shopify

$ brew install themekit

Once Themekit is installed, you can start working on modifying a theme through your text editor, like VSCode, rather than a browser window. Create a folder for your files, `$ cd` in, and run this command:

$ theme get --password=<password --store=<store> --themeid=<theme id>

• Find the <password> on Shopify — log into the specific client, then navigate to Apps > Manage private apps (bottom of the page) > ThemeKit (click in) > copy password*
  *Since publishing this in January 2022, the Manage private apps link has moved from the bottom of the app page in Shopify. Now, you can add the Theme Kit Access app and the store admin should receive the Theme Kit password in their email. More info from Shopify’s official documentation here.
• Find the <store> in the url in your browser (should be similar to store-name.myshopify.com)
• Find the <theme id> on Shopify — navigate to Online Store > Themes > choose theme > Edit code > copy theme id from URL (should be similar to 121276235841, a number at the end of the URL)

Finally, run $ code . to open the theme in your text editor and then $ theme watch so that Shopify will automatically update the theme. Any errors in your .liquid files will prevent the code from syncing, which also provides another layer of quality assurance — the theme visible on your browser will stop updating before it breaks. To turn off themewatch, simply run ctrl + c

Pt 2 — Schemas and adding Functionality

In addition to modifying the front end of your site, you can create settings in your front end code that are accessible to the admin of your Shopify account. This is helpful if you are working for a client that doesn’t have their own development team and needs to manage content or switch between different versions of a page without a developer’s assistance. Broadly, you will do this by creating fields in the Shopify backend that the client can control. You’ll create a checkbox, a text box, or any number of tools that allows them to toggle and update the look and feel of the front of the website.

The workflow for using schemas to add functionality is

1. updating the schema to create the fields that they see in the back end and
2. updating the relevant .liquid file to include conditional statements in Liquid

There’s more than one right way to use schemas, but one of the simplest and most powerful is adding an if / else operator in a <div> or other element so the styling turns on and off.

In your theme, navigate to /config/settings_schema.json to find the available fields for different settings in the Theme that show up on the Shopify backend. For example, this might be the JSON for the header of your Shopify site:

 {
   “name”: “Header”,
   “settings”: [
     {
       “type”: “header”,
       “content”: “Header Styling”
     },
     {
       “type”: “checkbox”,
       “id”: “header_gradient”,
       “label”: “Apply gradient to transparent header”,
       “default”: false
     },
     {
       “type”: “checkbox”,
       “id”: “nav_fonts_weight”,
       “label”: “Make header fonts bold”,
       “default”: false
     },
     {
        “type”: “header”,
        “content”: “Logo”
     },
     {
        “type”: “checkbox”,
        “id”: “logo_use_image”,
        “label”: “Use custom logo”
     },
     {
        “type”: “checkbox”,
        “id”: “meganavimage”,
        “label”: “Use MegaNav Image”
     },
     {
        “type”: “image”,
        “id”: “logo.png”,
        “label”: “Custom logo”,
        “max-width”: 450,
        “max-height”: 200,
        “info”: “450 x 200px .png”
     },
     {
        “type”: “text”,
        “id”: “logo_max_width”,
        “label”: “Max logo width”,
        “default”: “450”,
        “info”: “Defined in pixels. Do not add the ‘px’ unit.”
     },
     {
        “type”: “header”,
        “content”: “Favicon”
     },
     {
        “type”: “checkbox”,
        “id”: “favicon_enable”,
        “label”: “Use custom icon”
     },
     {
        “type”: “image”,
        “id”: “favicon.png”,
        “label”: “Icon”,
        “max-width”: 32,
        “max-height”: 32,
        “info”: “32 x 32px .png required”
     }
   ]
}

This JSON object includes a number of important parameters:

• type — this corresponds to what tool will show up on the Shopify backend. If you set it to “checkbox” there will be a checkbox. If you set it to “header” it will be a header for the settings. And so on.
• content — for “type”:”header” specifically, this corresponds to what the header will say in the settings.
• id — this corresponds to how you reference this setting in the .liquid file. If you name it “header_gradient” then you will reference it in the liquid file with settings.header_gradient
• label — this corresponds with the name of the field on the Shopify backend. if you name it “Header Gradient” it will show up as Header Gradient.
• default — specifically for checkbox, if you set the default to false (not “false”) then the box will be unchecked by default. If you set it to true, it will be checked by default
• info — this corresponds with the subtitle of the field on the Shopify backend. If you write “Click to apply gradient/vignette to transparent header” then under the checkbox on the backend you will see the same text underneath. This is good for instructions, file requirements, or more explanation if the title of the field is at all unclear.

To see the changes you’ve made in settings.schema.json in the Shopify admin, navigate to Themes > the theme you’re working on, and click on Customize, then Theme Settings. Click into the section you’re working on and you should see the changes from your settings.schema.json file show up on the left hand navigation. Make sure you reload after any changes to the .json file to see the schema reflect in the admin!

In a corresponding section you can add in the functionality that will make the settings you’re adding to the backend actually work. In these examples, the setting id is “my_setting”:

wrap whatever block of code that is meant to change in {% if settings.my_setting %} and {% endif %}. This means that if my_setting is checked (true) then the block is executed. Here’s an example of code from a .liquid file that corresponds to the header JSON schema above:

<div class=”header-sticky-wrap {% if template contains ‘index’ %}header-transparent{%endif%}” {% if settings.header_gradient and template contains ‘index’ %} style=”background-image: linear-gradient(to top, transparent, #373737);” {% endif %} >

Here, if the box is check on the back end, then if settings.header_gradient will evaluate to true and the style tag in the element will turn on. This is huge! You can create custom settings that anyone can modify, not just developers.

It’s worth noting that could also use the same conditional logic with class names, id names, or entire elements. The flexibility of these tools is a double edged sword: on the one hand, anything is possible, but this also means that there are a lot of opportunities for personal idiosyncrasies in styling from developer to developer. It’s important to use naming conventions that other developers (as well as future you) will recognize.

I hope this is a helpful reference for any developers new to working on Shopify Themekit and schemas! I also hope that I can continue to build on this series as I learn more about the ins and outs of Shopify frontend development. To that end: please let me know if you have any questions or ideas about features that I can explore.