Run Shopify Theme Check Before Every Handoff

What it is and why it’s free money

Theme Check is a linter that ships with the Shopify CLI. It reads your theme source and reports problems with file names and line numbers. It doesn't need a store connection, it doesn't need a running dev server, and it finishes in seconds.

shopify theme check --path .

The reason it's worth building a habit around isn't the volume of things it finds. It's the class of thing. A Liquid error referencing an object that doesn't exist on a product template doesn't degrade gracefully — it can take the page down. That's the failure mode most likely to be discovered by a customer rather than by you.

What it actually catches

Findings come with a severity. Treat them differently.

How to triage

• Errors: fix before handoff, no exceptions. These are the page-down class.
• Warnings: fix on your own code. On inherited themes, decide deliberately — note them rather than silently accepting them.
• Info: useful signal, not a gate. Unused assets on a five-year-old theme are expected.

What it can’t see

Being clear about the boundary matters, because a clean lint pass creates false confidence.

Theme Check reads source code. It never renders a page. So everything that only exists at render time is invisible to it:

• Layout and visual bugs. Overlapping elements, broken grids, text overflow.
• Cross-browser differences. A missing -webkit- prefix is valid CSS; Safari just ignores the property.
• Empty sections from missing data. A metafield binding with no definition is syntactically perfect.
• App conflicts. Overlays injected at render time aren't in your files.
• Real-world performance. It flags blocking assets; it can't measure what a page actually scores.
• Whether the design is right. Obviously, but worth saying to clients who hear "automated checks passed."

Making it automatic

A check you run when you remember is a check you don't run. Three places to attach it, cheapest first.

1. Editor integration

Theme Check powers the Liquid language server, so most editors can surface findings inline as you type. This is the highest-value version because the feedback arrives before the mistake is committed.

2. A pre-push habit

Wrap it with the deploy so it isn't a separate decision:

#!/usr/bin/env bash
set -e
shopify theme check --path .
shopify theme push --unpublished --theme "$1" --store "$STORE"

set -e is the point: if the check fails, the push doesn't happen.

3. A handoff gate

Put "Theme Check clean of errors" on the handoff checklist as a named item with a named owner. Findings from an automated check are also far easier to raise with a client than opinions — "the linter reports six errors on the current theme" is a fact, not a criticism of whoever wrote it.

How ThemeSync fits in

• Theme Check runs from the same place as your pushes. Linting sits alongside push, pull and package rather than being a separate terminal habit, so it's part of the flow.
• A separate compatibility scan covers what Theme Check doesn't. A static pass over CSS and JS flags cross-browser risks — backdrop-filter without -webkit-, flex gap on older Safari, unprefixed position: sticky, clip-path without a prefix — with severity, file and line.
• Visual capture covers the rest. Every mapped template across Chromium, Firefox and WebKit at desktop, tablet and phone sizes, so layout problems that pass every linter get seen.
• Performance is measured, not inferred. Scores for the templates that matter, so "blocking asset" warnings can be weighed against what the page actually does.
• Findings live with the theme. Scan results sit next to the templates and client sign-off for that theme, so a handoff has evidence attached.

Takeaways

• shopify theme check is free, local, and finishes in seconds.
• It catches the page-down class of bug: Liquid errors, undefined objects, missing templates.
• Fix errors always. Be selective with warnings on inherited themes, and don't chase zero.
• It reads source, so it cannot see layout, cross-browser rendering, missing data or app conflicts.
• Attach it to your editor and to your push script so it isn't a thing you remember.
• A clean lint pass is not a clean QA pass — say that to clients explicitly.