Technical debt in a Shopify theme, quantified

Why "the theme is a mess" never gets funded

Every merchant with a theme old enough to have opinions about it has heard some version of "this needs a clean-up." It is almost never followed by a budget, and the reason is not that the complaint is wrong. It is that nobody approving spend can act on a feeling.

A number changes that, but only if it survives the obvious follow-up question: how did you get it? A single proprietary "technical debt score" fails that test immediately, because the answer is "a formula we cannot show you." A count of specific, named things (how many orphaned snippets, how many templates still on the old architecture, how many assets over budget) survives it, because each one is a sentence a non-technical stakeholder can repeat back correctly.

So the exercise below is not a single metric. It is five, chosen because each is cheap enough to re-run every month and concrete enough to argue about.

Proxy one: what the linter already counts

Theme Check is Shopify's own linter for the Liquid and JSON in a theme, and running it costs nothing. It already exists, and most themes have never had someone read its full output rather than fixing whatever broke a specific build.

Track two numbers from it monthly rather than treating "zero issues" as the goal: total issues by severity, and the trend. A theme with 40 warnings that was at 65 last quarter is improving. A theme with 12 warnings that was at 4 last quarter is not fine because the absolute number is small. It is accumulating, and the trend is the thing worth showing whoever approves engineering time.

Two checks are the highest-value proxies inside this one. OrphanedSnippet counts files that exist but render nowhere, and UnusedAssign counts variables nothing reads. Both are close to a direct count of code nobody can currently explain the purpose of. Express each as a share of the theme's total snippet or assign count, not a raw number, so a small theme and a large one are comparable on the same scale.

Proxy two: how much of the theme is still on the old architecture

Online Store 2.0 gives a theme sections on every template, blocks inside sections, and settings at both levels: the architecture that lets a merchandiser build a page without a developer. A theme built or extended before that shift, or one where new templates keep getting added as plain .liquid files out of habit, is carrying a specific, checkable form of debt: pages that require a deploy to change something a JSON template would let a merchandiser edit directly.

This proxy needs no tool. Count templates in templates/ that are .liquid rather than .json, as a share of the total. A theme at 90% JSON with three legacy checkout-adjacent templates left over is a small, scoped migration. A theme still mostly .liquid is not a clean-up. It is the theme rebuild that the refactoring conversation eventually has to admit to.

Proxy three: how often the load-time budget is breached

Theme Check reports this directly, and it is the proxy most directly tied to a number a business already tracks: page speed. AssetSizeCSS and AssetSizeJavascript fail when a file exceeds a configured size threshold. ParserBlockingScript flags script tags without defer or async. RemoteAsset flags assets pulled from third-party domains instead of Shopify's own CDN.

Count failures across these four checks the same way as proxy one: by severity, by month, as a trend rather than a one-off pass or fail. Unlike the first two proxies, this one has a direct line to a metric the business already watches, which makes it the easiest of the five to get budget approval against: "fourteen scripts are shipping unminified or blocking parse" is a sentence a CRO stakeholder understands without translation.

Proxy four: blast radius, for the files that matter

The first three proxies count issues. This one counts risk, and it does not need every file measured, only the ten or fifteen most-included snippets and sections, which is usually where a theme's real fragility lives.

For each, grep the theme for every template and snippet that renders it. A snippet included from one template is a contained risk regardless of how untidy its code is. A snippet included from eleven templates, including ones nobody has opened since the last migration, is a standing liability that a three-line change can turn into an incident, and it is exactly the kind of debt a line-count-based review misses, because the diff looks small.

Record the count next to each file's name and revisit it after any restructuring work. A successful consolidation should reduce the number of high-blast-radius files, not just the number of lines in them.

Turning five numbers into a budget line

None of the above is technical debt by itself, and presenting five counts to whoever approves spend will not get the work approved either. It will get the same shrug as the original vibe, with more precision attached to it.

The conversion that works is hours. Estimate, from the last time your team actually did each kind of fix, how long resolving one instance takes: an orphaned snippet is minutes; a vintage-to-JSON template migration is hours per template; a blast-radius consolidation is a scoped project with its own estimate. Multiply each proxy by its per-instance cost and the five numbers become one figure with a currency sign in front of it, which is the artifact that actually gets a "yes."

Re-measure on the same schedule the figure was approved against (monthly is usually right for a trading store) and report the trend, not just the latest snapshot. A stakeholder who approved three months of clean-up wants to see the count falling; a single audit with no follow-up measurement is indistinguishable, from where they sit, from money that disappeared.

What we would not do

Buy a single proprietary "debt score" from a tool that will not show its formula. If a number cannot be explained in one sentence to the person approving the spend, it will not survive the meeting where the spend gets decided.

Grade every theme against theme-check:all, the strictest preset, and report the resulting gap as "the debt." As covered in refactoring a theme without a redesign budget, a gate set at the standard you aspire to just produces a permanently large number nobody acts on; measure against the baseline the theme already passes, and track movement from there.

Commission a full rewrite from one high total. The five proxies above are diagnostic, not a verdict: a theme can be high on proxy two (vintage templates) and low on everything else, which is a scoped migration, not a rebuild. Only recommend a rebuild when the numbers say most of the theme is affected across more than one proxy at once.

Questions this raises

Read next

• Shopify theme customization
• Refactoring a theme without a redesign budget
• Theme code review: what to look for