Alberto Vena

Have you ever struggled with a simple addition to your Shopify store turning into a nightmarish project, full of intricacies and edge cases? Or maybe you’ve experienced the impatience of looking at your product page take forever to load, longing for the good old days when it showed up instantaneously? Or perhaps you’ve run into weird UI bugs caused by two of your apps not playing nice with each other?

When you launch a new Shopify store, everything’s fantastic: the theme is beautiful, the pages load fast, and the apps you’ve picked are a joy to work with. It feels like you’ve got everything figured out, and no one and nothing will ever change that.

But after a while, some friction shows up. Implementing new features takes longer. Bugs pop up. Site speed decreases, as does your conversion rate.

Your team (or your agency) now spends more time hunting down the things that are not working than implementing new functionality that could move the needle. But even though everyone’s dissatisfied with the state of things and your business is suffering, no one can pinpoint the root cause or figure out a definitive solution.

Starting from scratch looks like the only option, so that’s what you do. You change agencies, rewrite your theme, and call it a day. Unfortunately, the rewrite only helps temporarily: give them enough time, and things will revert to their original state, and the cycle will start all over again.

Sounds scary, doesn’t it? And yet it’s a story that we’ve heard from many Shopify merchants, disenchanted with their agency, internal team, or the Shopify ecosystem as a whole.

The good news is that it doesn’t have to be like this. There’s a way to keep your ecommerce store from degrading over time; all it requires is a more thoughtful approach to store development. In this blog post, we’ll outline what that approach looks like, and how you can adopt it.

But before we do that, we need to introduce the concept of technical debt.

## What Is Technical Debt?

Technical debt, often called just “tech debt,” refers to the compromises made in a system for short-term gains, which may lead to more complex maintenance and updates in the long run. It is the practice of taking shortcuts: installing unvetted apps for the sake of shipping a feature, implementing untested JavaScript “hacks” in your theme, breaking best practices for theme maintenance, or failing to keep up with the latest Shopify API updates.

These solutions help you move faster and will not kill your store in the short term, which makes them so appealing in the first place. But in the long term, the consequences will show up in the form of bugs, lower site speed, a slowdown in development velocity, and, in extreme scenarios, a decrease in conversion rate.

Unfortunately, Shopify’s marketing can be misleading when it comes to technical debt: the promise is that, by using Shopify, merchants will never need to worry about technology, and by extension, they will never need to worry about technical debt.

That is only partially true: while Shopify handles a lot of responsibilities for merchants, a merchant’s theme and app stack is still for the merchant to maintain, and it can accumulate technical debt just like any other software. Your theme can either be a beautifully architected piece of technology, highly performant and easy to evolve, or a hot mess of obscure hacks and patches no one understands anymore. You, the merchant, are ultimately responsible for deciding where you want this pendulum to swing.

But in practice, what are the sources of technical debt in Shopify that cause stores to lean one way or the other? Here’s a non-exhaustive list, but keep in mind that there are additional factors that are often unique to each store:

* **Multiple stores:** even after the advent of Markets and B2B in Shopify, many merchants keep using multi-store setups when they are not needed. Because each store is independent and stores can diverge from each other, this setup can be a significant source of technical debt, increasing the cost and complexity of making changes.
* **Too many apps:** Shopify’s blessing–its app ecosystem–is often its curse. When we audit Shopify stores, we are often shocked by how many apps the average store has installed. Often, not even the merchant can explain what all the apps do. This is the #1 source of bugs, compatibility issues, and a steep increase in license fees.
* **Too much JavaScript:** some custom themes present a large amount of JavaScript code, often using external libraries such as React, Angular, or jQuery. This complexity, which is sometimes uncalled for, makes it harder for developers to find their way around a theme, slows down your website, and introduces bugs.
* **Large Liquid files**: similar to the point above, Liquid files that are hundreds of lines of code quickly become hard for developers to understand and change, to the point where they might be deemed completely unmaintainable.
* **Outdated code:** if your store is not leveraging metaobjects or not using the full potential of Online Store 2.0, you might end up with weird hacks and workarounds to implement functionality that is now natively available in Shopify. Apps can compound this problem because they are sometimes slow to adopt new Shopify APIs and capabilities, reducing the flexibility and optionality of their user base.

There are additional factors that are not technical debt _per se_ but often lead to technical debt over time: examples of these would be the lack of a defined QA process for theme changes, which increases the likelihood of bugs, or the lack of theme documentation, which makes it harder for unfamiliar developers to find their way around the project.

## A Three-Step Approach to Managing Shopify Technical Debt

Managing technical debt in a Shopify store can be tricky for inexperienced merchants and developers. However, a structured approach can go a long way in effectively controlling it. Here’s the three-step process we typically adopt when we work with a merchant.

### 1. Measure the Business Impact

Before tackling technical debt, it's essential to understand the extent of the problem.

In traditional software projects, there are tools that attempt to measure the health of your code. These tools typically ingest your entire codebase and produce a “quality” score that tells you the overall state of the software and what areas you should improve.

The bad news is that most of these tools don’t work with Shopify themes because they’re structured differently than most other software. The good news is that, in our experience, such tools are ineffective: technical debt only matters insofar as it _actually_ impacts your business. Code quality, as measured by a machine, is rarely a good proxy for business impact.

Instead, you want to measure the effects of technical debt on your store’s real-world performance. There’s no one-size-fits-all metric here, but here are some that we’ve used:

* **Defect rate,** which measures the number of features your team has shipped that introduced one or more bugs in the customer experience.
* **Cycle time,** which measures the time it takes for your team to implement a change after that change has been prioritized.
* **Site speed,** which should be pretty self-explanatory.

Both defect rate and cycle time can be measured with a good project management tool, while site speed is typically measured with tools such as PageSpeed Insights.

With all these metrics, what matters most is not their absolute value but their directional trend over time: if they’re getting better and not worse, you’re moving in the right direction and can double down on your current approach.

### 2. Establish a Solid Foundation

Once you have a good grasp of the extent of the problem, the next step is to ensure there are no obvious sources of technical debt in your Shopify setup.

These are the aspects we typically focus on:

* **Leverage native Shopify features**: by using native functionality as much as possible, you are reducing the need for ongoing maintenance. Whenever you diverge from the built-in functionality, you should always consider the balance between innovation and the additional complexity you’re introducing into your store.
* **Minimize third-party apps**: in addition to increasing your license fees, each app you install into your store introduces more complexity, potentially slows the website, and can lead to bugs in the customer experience. Vet all the apps you install and ensure they are needed.
* **Adopt a version control system (VCS):** a VCS makes it much easier to document the changes developers are making to your theme, and to roll back to a previous version of the theme in case a bug pops up. From a technical standpoint, there’s no reason not to have a VCS in place for your Shopify theme.
* **Set up a test store:** a staging environment (sometimes called a “test store”) allows you and your ecommerce development team to test your changes safely before rolling them out to your customers. The caveat is that you will likely need to install all your apps in the staging environment, increasing your license fees.

While this is just the beginning, it will give your team an initial foundation they can build upon.

### 3. Prevent and Reduce Debt Over Time

With the basics in place, you can now adopt team-wide policies to help your team minimize the technical debt you introduce over time.

These are some of the policies that we adopt:

* **Call technical debt by its name:** if you only do one thing outlined in this article, it should be this. The #1 reason technical debt keeps growing is that developers do not have the technical understanding or psychological safety to talk about it. Ensure everyone is familiar with technical debt and comfortable calling out when a corner has been cut. A recurring team retrospective can be very helpful here.
* **Perform technical code reviews:** encourage developers to review each other’s code whenever a change is introduced. This means that developers will need to schedule time for code reviews, and your development velocity will slow down a bit, but the quality of the end product will benefit tremendously.
* **Establish a structured QA process**: ideally, QA should be done on every new change by your development team, who should be familiar enough with your store to understand whether a feature meets all the acceptance criteria. If that’s not possible, you can also designate the person in charge of website development.
* **Set time aside for tackling technical debt:** in the past, Shopify shared their internal strategy for dealing with technical debt, the [25 Percent Rule](https://shopify.engineering/technical-debt-25-percent-rule). It might not work for everyone, but having a clear understanding of how much time is acceptable to dedicate to refactoring technical debt will create a safe space for developers to work on it.

Some of these policies might be overkill for small stores, while others must be adapted to your needs. Ultimately, it all boils down to how much technical debt impacts your store and how many resources you can dedicate to fighting it.

## Technical Debt Is a Tool: Learn to Use It!

With this entire article focusing on eliminating and preventing technical debt in your Shopify store, you might be tempted to think that technical debt is something to be avoided at all costs. The reality is a bit more nuanced.

Like financial debt, technical debt is a tool: cutting corners helps you move faster at critical times of your business, such as before a big launch or public holiday.

And _just like_ financial debt, technical debt must also be paid off at some point. If you ignore it, its adverse effects will compound over time, severely impacting team morale and dragging down business performance.

Leveraging technical debt thoughtfully and intentionally is critical to a merchant’s success in the Shopify ecosystem. Doing it well requires a collaborative effort, with clear team agreements and robust processes tailored to your growth stage and team composition.

If you’re struggling with managing technical debt in your Shopify store, [reach out!](https://nebulab.com/contact-us) As a Shopify partner, have worked with some of the largest brands in the ecosystem and can help find the best solution for your store.


The Nebulab

How To Manage Technical Debt in Your Shopify Store