Best practices for Shopify theme development

Today's post is written by Carlos Villavicencio, who is one of our developers at Stack Builders. Carlos has extensive experience with Python, and has actually been a speaker in two renowned Python conferences last year: PyCon Colombia and PyCon China. He's also proficient with other languages and technologies, and in this article he will give us his developer insights about the Shopify platform.

At Stack Builders we have experience with Shopify projects, and would be glad to work with you if you're using it for your business. Contact us if you're interested in pushing your Shopify store to the next level!

Introduction

Shopify is an e-commerce service that makes life easier for online stores. It provides a great look and feel through customization using simple HTML and JavaScript. However, there are some store owners that need to build complex logic and integrations in their stores in order to scale and satisfy their customers’ needs.

I have worked with many different kinds of stores and I’ve noticed some improvements that you can easily adopt to increase your scalability and maintainability for a Shopify project. In the following sections, we will explore some of these patterns and improvements one by one.

Before moving on, I wanted to list the main technologies that we need to work on regarding Shopify themes. This is a front-end stack, so HTML as a markup language with JavaScript to implement client-side logic. To manage the JS ecosystem, some knowledge of Node.js is required. And lastly, CSS for styling our final work.

Themekit

Themekit is a useful CLI created by the Shopify team that is used to deploy our local changes to our shop’s theme. It also provides the watch functionality which detects any changes on our theme’s files and uploads it automatically. This is a huge timesaver during the development process.

Version control

There are several version control systems of which Git is very popular. The main advantages are that we can host our source code and its versions in platforms like GitHub or GitLab. It increases team collaboration and we have the option of doing a rollback to a previous version if we determine a recent update is not working as expected.

Please keep in mind, if you need to store large files like videos it’s highly recommended to use Git LFS. This extension stores a file pointer in our repository instead of the “real” heavy file (e.g. a video).

Ignoring files

There are some files that change over time in their own production environment, so we don’t want to overwrite them. I recommend that you ignore the settings changed by store admins that are located in the config/settings_data.json file. Also, it’s a good practice to ignore all files that are auto-generated by external scripts.

There are some patterns that are recommended by Shopify that can be ignored in Themekit’s configuration. Find out more about this in the official documentation.

Node Package Manager

We should have a centralized place to manage and keep our dependency tree up-to-date. For this, we can use the Node Package Manager. The npm is a free registry where it’s possible to find millions of open-source JavaScript libraries ready to be used in your projects.

Having Node.js enables it so that we can add a lot of enhancements to our project which I will go into more detail about in the next sections.

Use linters

ESLint is a useful tool that locates and fixes problems within the code. Prettier is a nice compliment to the aforementioned tool. It is an opinionated code formatter that supports many languages and works with a lot of editors. There’s a way to set up them in a Git hook so it will analyze and format the code before pushing it to the repository.

Scope global variables

Sometimes we need to pass values rendered by our Shopify “back-end” into our theme logic. Since those values are known at runtime, a common way to hook them to our code is to define a variable within the global scope (using var) in our template file.

var allProducts = “{{ products | json }}”;

There is a more manageable way to maintain these kinds of variables. You can store them inside a common object in the global window object. You can name it as your store, which will help you to quickly find the location where these variables are being used since all of them will be in the window.MY_STORE object.

window.MY_STORE.allProducts = “{{ products | json }}”;

Set up a bundler

Are you experiencing a large problem? Don’t forget to divide and conquer. For this, you might need a straightforward way to concatenate your code into a simple theme.js file that will be included in your application. There are plenty of options for this. If you just want to concatenate sources, a gulp task should suffice. If you are using ES6 features and modules, then Babel is a tool you should consider. webpack is also another great tool. Configuring those tools is not within the scope of this post but the goal is to have a pipeline that transpiles our code to browser-compatible JavaScript, optimizes, minimizes, and generates additional developer tools such as source-maps.

Pro tip: you can add a task to watch your source changes and generate your bundle every time. Using this along with Themekit watch will boost your productivity immensely.

Assets organization

Shopify only allows you to save your application assets in the assets directory with no subdirectories, as they state in their documentation. However, there’s a way to keep your project well organized. You can add a directory elsewhere (e.g. files) and this way your content will be more effectively organized. It is also possible to have separate subdirectories such as styles, videos, images, svg, according to the kind of assets your project uses. With some bundler tasks, you can copy all the required files into a flat assets directory as Shopify wants.

Modularize your code

If your project is getting larger, this could mean that your store is growing. This is a good thing! But at the same time, your code can become harder to maintain. A common recommendation is to split your code into different source files. You can create your directory structure to organize your scripts better.

Testing

One important practice in the software development world is Test-Driven Development. Here, tests should be written first, next write the code that satisfies them. Using TDD can improve your software design, robustness, quality, documentation, and ease maintenance. You can add tests incrementally to your code-base. To start with, begin your focus on testing pure functions (functions with no side effects), then you can test UI components, mock services, and everything you need to have a happy coverage.

You can also include Jest to write all your unit tests. It has a watch script too, so every time you create new features, you can now immediately test, bundle, deploy, and enjoy!

TypeScript

Do you love to use a static check analysis so bugs can be detected at the development stage? And do you write safe, robust, and maintainable code using types? If this is the case, you will be happy to hear that you can write your Shopify theme using TypeScript. Haven't used it before? TypeScript extends JavaScript by adding types and strict rules. Now that you have your code as ES6 modules and have a bundler in place, you only need to set-up the TypeScript compiler and voilà! Let’s bring some type safety to your next application.

Continuous Integration

The cherry on top of the cake is to have continuous integration in place. CI is the practice to merge your changes into the mainline, running all unit tests and deploying the final application if possible once all of our project’s checks have passed.

There are a lot of options to choose from. My advice, in this case, is to go with GitHub Actions. This tool can be easily integrated into your application’s repository. You can automatically perform some of the steps that I’ve previously mentioned like linting, testing, and bundling on every code push. It’s worth mentioning that your CI workflow can also become a Continuous Delivery one. Using this particular action in combination when a PR is merged, you can automatically deploy your code into a specific Shopify theme, so QA can be performed right away.

Conclusion

Shopify is a service that gets more popular everyday among the online sellers. The customization level that can be achieved is huge.

As I’ve detailed in the previous points, it’s possible to integrate a set of tools that optimize your recurring tasks. Most of them can help you perform early bug detections in order to prevent unexpected behaviors while the project is running in production. Most importantly, the technical debt will decrease as you keep coding aligned with your own guidelines and best practices. Do you use another tool that helps you in your project’s workflow? Let us know on our social media accounts!