If there’s one thing we have discovered since releasing Slate into the wild, it’s the incredible number of different workflows developers have when building Shopify themes. And while there isn’t one development workflow that rules them all, we at Shopify continuously strive to make our lives easier and more efficient by integrating tools and resources that we believe in.
We believe Slate is one of those tools, and it’s something we’re quite proud of. It provides a sophisticated development experience that enables users to build top-notch Shopify themes. In regards to development workflow however, it’s only one piece of the theme puzzle.
This guide will serve as a helpful analysis of what we find to be the most effective, tried-and-true methods, tools, and resources that help speed up our own development process as we build Shopify’s free themes.
You might also like: Level-Up Your Theme Development with the Next Release of Slate.
Setting up your code editor
The Shopify Themes team has been using Visual Studio Code over the last year, and it has helped improve our productivity with the ability to customize our own workspaces, settings, and extensions.
Apart from being free, open sourced, and functional on any operating system, it contains the vast majority of features we love having in a code editor, like smart completions with intellisense, amazing debugging tools, and Git support already built-in.
While this won’t be an exhaustive list of all Visual Studio Code extensions we use, it will include what we found to be the most crucial in increasing our productivity when building Shopify themes.
Liquid Template Snippets
We use Liquid every day. Unfortunately, Visual Studio Code doesn’t ship with support for Liquid out of the box, which means it won’t correctly recognize any Liquid syntax highlighting and snippets you may want to have while developing Shopify themes.
You can get around this by installing the Liquid Template Snippets extension, which will include syntax highlighting for all
.liquid files as well as auto-completion for common Liquid tags and filters.
If you’re looking to set syntax highlighting for
.js.liquid files, you will need to update your Visual Studio Code user settings:
console.log will result in ESLint throwing an error.
Stylelint is the ESLint for CSS. It reports any issues in your CSS code, for example malformations with your indentation, empty code blocks, and disallowed
!important declarations for your CSS properties.
Download the stylelint extension and learn more on the stylelint website. Update your Visual Studio Code user settings to include the following in order to prevent the same errors being reported more than once:
Consistent formatting across multiple developers working on the same project can be tedious. Prettier is an opinionated, yet configurable, code formatter that takes the worry out of having to format your code manually. And the best part is, it works really well with both the ESLint and Stylelint extensions.
Download the Prettier - Code formatter extension and add the following to your Visual Studio Code user settings to ensure you take advantage of its capabilities:
Getting started with themes
Every new Slate project is generated by running one simple command. You can currently choose from a number of different starting points.
Before continuing, you’ll want to ensure you have the necessary system requirements to work with Slate.
You can also visit the theme documentation to learn how to customize and create your own Shopify themes.
Choosing a starting point for your project
Depending on the level of your theme development knowledge, you may want to start a new project with Shopify’s opinionated theme boilerplate code, i.e. Starter Theme, or a more barebones version only containing the necessary file structure, i.e. Skeleton Theme. We have a full article about how to work with either of these starter themes.
Run the following in your terminal to generate a new Slate project:
yarn create slate-theme my-new-theme
my-new-theme argument is the name of the folder and needs to be appropriately named. You can also pass the
--skipInstall flag in order to skip installing the project’s dependencies. If you pass this flag, you will want to ensure you run
yarn install or
npm install after the theme has been generated.
If you chose to use npm 5+ over Yarn, it ships with a binary alongside the usual npm package called npx. Replacing
yarn in the command above with
npx will result in the theme project being generated in the same way. To learn more, see the documentation for the Create Slate Theme package.
You might also like: How to Create Your Own Slate Starter Theme.
Starter Theme and why you should use it
Starter Theme is the default starting point when generating a new Slate project. It represents Shopify’s opinionated approach to building themes and includes up-to-date best practices and solutions that we have deemed necessary for the majority of themes we build.
Keep in mind that Starter Theme is not a framework, but rather a minimal boilerplate. It is set up in such a way that the templates and snippets included consist only of the Liquid tags and logic that will most likely be used. The files contain little to no markup, classes, or any other code that will get in the way of your development.
Learn more about Starter Theme’s project structure.
Custom starting points
It’s common for developers to reference our free themes when building their own projects. However, we understand not everyone shares the same approaches to solving problems. This is why Slate allows you to create and define your own custom starter themes.
Whether you work by yourself or in a team of multiple developers, this section will help define a development workflow that works for you by exploring the approaches the Shopify Themes team takes when developing a theme.
Version control: GitHub
We use GitHub extensively every day and it represents the foundation for our development workflow.
Each one of our projects is hosted in its own repository, including all of our free themes as well as Slate. We love this because each repository allows us to focus on individual project concerns: adding updates, creating issues and pull requests, and writing documentation refers to only one project at any given time.
We recommend having a look at the GitHub glossary to get a better understanding of some of the terms that are commonly used in the GitHub world.
Using branches for theme updates
Branching is the core concept in Git, and we approach it by thinking of individual branches as a separation of concerns. If we’re working on a new theme feature or a bug fix, we’ll first create a branch, open a pull request, and finally merge the code into the
master branch once the code has been reviewed.
To ensure you have the latest updates before creating a new branch, run the following:
git checkout master
git pull origin master
git checkout -b fix-toggle-button-position-in-featured-collection
This will switch to the
master branch, pull the latest changes, and create and switch to a new branch called
While the Themes team doesn’t enforce strict branch naming conventions, we try to be as descriptive as possible with branch names, no matter the length, in order to make it clear what part of the theme is being worked on.
After pushing a new branch to your theme repository, you will see a notice that pops up on the front repository page which enables you to create a pull request:
For more information on how branches can be handled, read the GitHub flow documentation.
Working with theme IDs
The use of theme IDs for theme development can sometimes be seen as an untapped resource. You can think of a Shopify store having multiple instances of the same store: your published theme and zero or more unpublished themes, where each theme instance has their own independent theme ID.
Each developer in the Shopify Themes team has their own Shopify Partner account and develops independently from one another. This allows us to work on the same theme but in separate contexts without any overlap.
And while this depends entirely on the size of your team and how you develop, the approach we take is to create a new unpublished theme on our own respective store and work on that theme ID whenever we’re working on adding a new feature or fixing a bug.
This is useful because it allows each developer to work on a separate issue without affecting any other aspect of their store. It also helps us share each separate instance of our store with other developers when we need code review and testing.
The same development approach can be be applied to a team with multiple developers working on the same Shopify store.
Configuring one or multiple environments
Slate allows you to define one or multiple environments for your project. The
.env file is set as a sensible default that typically contains your development environment settings.
Alternatively, you can specify an unlimited number of other environments for your project. For example, a specific theme ID that is chosen to act as a staging environment allows you to create a
.env.staging file for that specific theme ID. You can then specify a
--env=staging flag when deploying your theme to your Shopify store.
To learn more about configuring environment files, view the “Connect to your store” documentation on the Slate Wiki.
A note about
SLATE_IGNORE_FILES isn’t the only configurable environment setting, it is the only optional setting and it enables you to ignore certain files from being deployed to your Shopify store.
Developers are typically confused when seeing their live store’s settings completely wiped out when first deploying their project. This usually occurs because of two reasons:
SLATE_THEME_IDis assigned to your published theme
One recommended usage for this would be to ignore the
settings_schema.json files to avoid overwriting your theme’s settings every time you deploy your theme. However, if you are adding new theme settings or tweaking existing ones, you will want to ensure these files are not being included as ignored files.
The file paths are relative to the theme’s
src/ directory so ignoring the
settings_schema.json files would look like the following:
Note: if you want to ignore multiple files, use a “:” to delimit the file paths.
Express server and local assets
Once you’re ready to start developing your theme, run the following command in your terminal:
This compiles your local theme files to a
Note: Because we’re running the server on
https://, you will need to visit the URL at least once and tell your browser to “trust it”. Otherwise, local assets will be blocked and your theme will appear broken. Alternatively, we recommend you create a trusted SSL certificate for
Sharing your theme ID
To avoid this, run the following command:
This will prepare your theme for a production build by compiling your assets and uploading them to your remote Shopify store. You will want to run this command anytime your theme updates are finalized.
We recommend duplicating the current development theme ID and running
yarn deploy for the newly created theme ID. This allows you to continue working on the development theme ID if further updates need to be made.
In the Themes page in the admin, if you click on a theme ID’s ‘Actions’ dropdown and select ‘Preview’, a new tab will open and the admin bar will pop up. You can then select ‘Share preview’ in the bottom right, click ‘Copy link’, and share it!
A proper release cycle
Now that we have a grasp of what we find to be the most important workflow topics, let’s look at how we approach a proper release cycle.
We think it’s beneficial that the states of both the GitHub repository and Shopify store are synced. Meaning, if you have a development branch that was created on GitHub, you have a theme ID on your Shopify store that is associated with that branch. Over time, the development branches are merged into the
master branch and their corresponding theme IDs are removed from the store.
master branch represents the most up-to-date version of your theme. From this branch, you can create new releases that you can then push to your Shopify store.
The release cycle would look like the following:
branch-1theme ID on your Shopify store
branch-1development branch in theme repository
- Update environment settings to reflect the theme ID
- Create pull request for new feature, bug fix, etc.
- Merge pull request into the
- Create a new GitHub release (e.g. RC1)
- Deploy the new release to a RC1 theme ID
- Test thoroughly
- If everything checks out, publish the RC1 theme ID to your live store
Note: a release does not need to be created every time a pull request is merged into the
master branch. New releases can be created arbitrarily based on your team’s own output.
We follow semantic versioning when creating new GitHub releases.
You might also like: Unite 2018 Keynote Roundup: Bringing Commerce to Everyone, Everywhere.
The following are tools that we use internally to ensure that we end up with well-tested and production-ready releases for our themes.
Continuous Integration, or CI, is a development practice that forces developers to check in their working code to a shared repository. Each check-in is verified by an automated build, allowing teams to detect any issues with the code for every commit.
There are multiple services that integrate very nicely with GitHub. At Shopify, we use Travis CI for our open source projects, including Slate.
After adding your repository to the Travis CI dashboard, you can create a
.travis.yml file in the root of your theme and add the list of scripts you would like to run any time new code is pushed to the repository.
If at any time you push code that fails the tests, the pull request will show the following notice:
.travis.yml file is already included in Starter Theme and Skeleton Theme.
Issue and pull request templates
Whenever creating a new issue or pull request, problem descriptions should be isolated to a single area of focus and have a meaningful title. Labels, if applicable, should be set so that issues and pull requests are properly categorized within the repository.
Issues should state the problem clearly and include steps so that other developers can replicate the issue. Pull requests should be small and featured based which allows for better code reviews and quicker approval.
To keep consistent across the text structure of your issues and pull requests, you can define both your own issue template and pull request template by creating a
.github folder in the root of your theme directory and adding the
pull_request_template.md files respectively.
While the code in a pull request needs to pass review, sometimes a pull request relates more towards a UX specific issue and simply needs testing in certain browsers and devices. In this case, we like to include a list of related links associated with the pull request: a demo store containing the theme ID that is currently being worked on, and any design mockups to compare the pull request to.
Developer Tools app
The Developer Tools app is a macOS app that connects to your Shopify development stores.
If you created a brand new Shopify development store, populating a store with fake data can be a lengthy task that cuts into your development time. While the Developer Tools app allows you to do several different tasks, the most relevant for Shopify theme developers is its ability to generate dummy content for your store.
Learn more about the Developer Tools app on the documentation page.
Suit your own needs
While there isn’t one development workflow that works for all teams, we hope this guide will help you become more efficient during your own Shopify Theme development. Draw inspiration and tweak it to suit your own needs as a developer.
Starter Theme is the culmination of the Shopify Themes teams’ efforts in enforcing what we find to be the best practices for developing Shopify themes, and includes out-of-the-box solutions for many of the topics discussed in this guide.
Improve your workflow and speed up the process of developing, testing and deploying your Shopify theme by running:
yarn create slate-theme my-new-theme
Have any tips from your own development workflow? Let everyone know in the comments below.