How to Improve Your Theme Development Workflow

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. Learn more about working with Shopify Theme Kit.

Setting up your code editor

The Shopify Themes team has been using Visual Studio Code (check out our best Visual Studio Code extensions!) 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.

You might also like: Level-Up Your Theme Development with the Next Release of Slate.

Extensions

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 .scss.liquid and .js.liquid files, you will need to update your Visual Studio Code user settings:

"files.associations": {
  "*.scss.liquid": "scss",
  "*.js.liquid": "javascript"
},

Linting is the process of running a program that analyzes your code for potential errors. We use two different utilities to lint our JavaScript and CSS code: ESLint and Stylelint.

ESLint

ESLint is a highly configurable tool for identifying and reporting on patterns found in JavaScript code. For example, creating a variable that is never used in your code or using console.log will result in ESLint throwing an error.

Download the ESLint extension to maintain consistency across your JavaScript files and help with any unforeseen bugs that may occur down the road! Learn more on the ESLint website.

Stylelint

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:

"css.validate": false,
"less.validate": false,
"scss.validate": false,

Prettier

While ESLint and Stylelint report any errors you may have contained in your JavaScript or CSS code, Prettier makes things, well… look prettier.

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:

"editor.formatOnSave": true,
"prettier.eslintIntegration": true,
"prettier.stylelintIntegration": true,

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

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

Development workflow

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 fix-toggle-button-position-in-featured-collection.

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

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

1. SLATE_THEME_ID is assigned to your published theme
2. SLATE_IGNORE_FILES is empty

One recommended usage for this would be to ignore the settings_data.json and 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_data.json and settings_schema.json files would look like the following:

SLATE_IGNORE_FILES=config/settings_data.json:config/settings_schema.json

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:

yarn start

This compiles your local theme files to a dist directory, uploads these files to your remote Shopify store, and boots up a local Express server that will serve your CSS and JavaScript assets from https://localhost:8080.

In comparison to server-side Liquid that needs to be uploaded to your Shopify store, client-side CSS and JavaScript assets are served locally because it leads to much faster development, and means that we can take advantage of Webpack’s Hot Module Replacement.

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 localhost.

Sharing your theme ID

Developers wanting to share an instance of their store with others are often confused when they see their store appear broken. Because CSS and JavaScript are being served locally, your theme won’t function on any machine other than the one the Express server is currently running on.

To avoid this, run the following command:

yarn deploy

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.

A repository’s 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:

1. Create branch-1 theme ID on your Shopify store
2. Create branch-1 development branch in theme repository
3. Update environment settings to reflect the theme ID
4. Create pull request for new feature, bug fix, etc.
5. Merge pull request into the master branch
6. Create a new GitHub release (e.g. RC1)
7. Deploy the new release to a RC1 theme ID
8. Test thoroughly
9. 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.

Other considerations

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

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:

Note: A .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 issue_template.md and 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

Happy development!