Skip to content
Tutorials Center
My learning

Topics

Lesson 43 of 61 ยท Performance and Quality

Theme Check, Linting and Testing

Catch Shopify theme bugs before merchants do: run Theme Check, configure .theme-check.yml, gate pull requests in GitHub Actions and Lighthouse CI, and test in the editor.

Themes are code that merchants edit, apps inject into, and shoppers load on slow phones. Without a safety net, a deprecated filter, a missing image size or a typo in a section schema reaches production. Shopify themes have no unit-test framework like a backend app does, so quality comes from a stack of cheaper checks: a linter that reads your Liquid, a performance budget, a preview theme you click through, and a short manual test in the theme editor.

This lesson walks through that stack. You will learn what Theme Check looks for, how to configure it with .theme-check.yml, how to run it in continuous integration (CI), how to add a Lighthouse budget, and what to test by hand. Commands and configuration target the current Shopify CLI (3.x); the CLI changes often, so confirm flags with shopify theme check --help on your machine.

Theme Check, the CLI and GitHub Actions run on your machine or on GitHub, not on this site. The configuration and workflow blocks below are read-only. The runnable examples are stand-ins: a tiny linter written in JavaScript that applies five rules in the same spirit as the real ones, and a budget gate that mimics a CI step. They are not Theme Check's implementation and they find far fewer problems.

What Theme Check is

Theme Check is Shopify's linter for themes. It parses your Liquid and the HTML around it and reports problems in three severities: error (will break or is invalid), suggestion (works, but there is a better way) and style (consistency). It ships inside the Shopify CLI, so you can run it from the theme folder:

Terminal
shopify theme check
shopify theme check --fail-level error
shopify theme check --auto-correct

The first command lists every offense. --fail-level sets the lowest severity that makes the command exit with a failure code, which is what CI needs. --auto-correct fixes the offenses that have a safe automatic fix. The same engine powers the squiggly lines in the Shopify Liquid extension for VS Code, so you see problems while you type, long before CI runs. The CLI itself is covered in Setting Up: Dev Store, Partner Account and Shopify CLI.

Some of the rules you will meet most often:

Rule What it catches
LiquidHTMLSyntaxError Broken Liquid or HTML, such as an unclosed tag
UndefinedObject Using an object that does not exist in that file's context
UnusedAssign A variable you assigned but never read
DeprecatedFilter, DeprecatedTag Old filters such as img_url, or the include tag
ParserBlockingScript A script tag with src but no defer or async
ImgWidthAndHeight An img without width and height, a layout shift risk
RemoteAsset Loading CSS or JS from another domain instead of your assets
MissingTemplate A reference to a snippet or template that does not exist

Rule names and defaults evolve, so treat this table as a map, not a contract. Each rule explains itself in the output, and the documentation for the linter lists the current set.

Configure it with .theme-check.yml

Put a .theme-check.yml file in the theme root. It starts from a preset and overrides what you need:

YAML
extends: theme-check:recommended

ignore:
  - assets/vendor-*.js
  - node_modules/**

ImgWidthAndHeight:
  enabled: true
  severity: error

AssetSizeJavaScript:
  enabled: true
  threshold_in_bytes: 100000

UnusedAssign:
  enabled: false

extends picks a preset: theme-check:recommended is the sensible default, and there are stricter and emptier ones. ignore skips paths, which is right for third-party minified files you do not own. Each rule is a top-level key where you can set enabled, severity and rule-specific options such as a size threshold. Disable a rule in the file, with a comment saying why, rather than leaving errors that everyone learns to ignore. A linter that always shows 40 warnings stops being read.

You can also silence one line in a Liquid file with a comment tag such as {% # theme-check-disable ParserBlockingScript %}, and turn it back on with theme-check-enable. Use it sparingly, with the reason next to it.

A stand-in linter you can run

To see how a rule engine works, here is a toy version. Each rule is a function that looks at one file and returns offenses, and the config decides which rules run and how severe they are. The real Theme Check parses Liquid into a syntax tree, so it is far more accurate than these line-based regular expressions.

JS A tiny Theme Check stand-in

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice three things that match the real tool: ignored paths are never read, config can lower a rule's severity (the remote script is only a suggestion), and the process result depends on the fail level, not on how many offenses there are. What does not match: the real rules understand Liquid structure, so they do not mistake text inside comments or strings for code.

Running checks in CI

A check that only runs on your laptop will be skipped on a busy Friday. Put it in your pull-request workflow so a broken theme cannot merge. Here is a GitHub Actions workflow (read-only; adjust the Node and action versions to what is current when you read this):

YAML
name: Theme quality
on: [pull_request]

jobs:
  theme-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install -g @shopify/cli
      - run: shopify theme check --fail-level error

Shopify also publishes ready-made actions for Theme Check and Lighthouse CI; the exact action names and tags change, so read their repositories before pinning one. Version Control and Team Workflows covers the branch and GitHub integration side of this.

flowchart LR
    PR["Pull request"] --> TC["Theme Check<br/>--fail-level error"]
    TC -->|pass| PV["Preview theme<br/>from the branch"]
    TC -->|fail| STOP["Fix and push again"]
    PV --> LH["Lighthouse CI<br/>against the preview URL"]
    LH -->|within budget| MG["Manual editor test<br/>then merge"]
    LH -->|over budget| STOP

Cheap automatic checks run first; the expensive human check runs last.

Lighthouse CI and performance budgets

Lighthouse measures a page in a lab: Largest Contentful Paint (LCP), Cumulative Layout Shift (CLS), Total Blocking Time and a combined performance score. Lighthouse CI runs it on every pull request against the preview URL and compares the result with a budget. Because lab numbers vary between runs, the usual practice is to run three to five times and compare the median. What the metrics mean is explained in Theme Performance and Core Web Vitals.

JS A performance budget gate

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The median is the point of the exercise: one noisy run should not block a merge, and one lucky run should not hide a regression. The values and the budget are invented; set yours from the real numbers of your current live theme.

Testing in the editor and with preview themes

Automated checks cannot see how a merchant will use your theme. Before you merge, push the branch to a preview (an unpublished theme, or shopify theme dev locally) and click through a short script:

  • Add, remove, reorder and delete every section and block type in the theme editor, and check that nothing breaks with the settings empty.
  • Check that each section looks acceptable with no content, with one block, and with the maximum number of blocks.
  • Switch the color scheme and the language, and open the page at phone width.
  • Confirm that dynamic updates still work after the editor reloads a section: JavaScript must handle the editor's section events (see JavaScript in Themes).
  • Test product pages for a product with one variant, many variants, a sold-out variant and no image.
  • Use a keyboard only for the header, cart and forms (Accessibility in Themes).

Write this list in the repository so it is the same for every release; Testing, Publishing and Going Live extends it into a launch checklist. Visual regression tools that compare screenshots of preview pages can help for large themes, but they need a stable store with fixed demo data, so start with the manual script.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does shopify theme check --fail-level error control?

    The fail level decides when the process exits non-zero. That exit code is what lets CI block a pull request while still showing lower-severity offenses.
  2. 2. You have a minified third-party slider in assets that you do not maintain. What is the cleanest way to stop Theme Check from reporting on it?

    The ignore list skips paths you do not own, while all rules stay active for your own files.
  3. 3. Why do Lighthouse CI setups usually compare the median of several runs against a budget?

    Network and CPU noise move lab metrics from run to run. The median reduces the chance that one outlier passes or fails a build by accident.
  4. 4. Which problem can Theme Check NOT find for you?

    Static rules read code. How a section feels with empty content or at its block limit needs a person to try it in the theme editor.

Summary

  • Theme Check lints Liquid and HTML, reports errors, suggestions and style issues, and ships in the Shopify CLI and the VS Code extension.
  • .theme-check.yml extends a preset, ignores paths you do not own and tunes rules; disable rules deliberately, not by habit.
  • Run shopify theme check --fail-level error in your pull-request workflow so offenses block a merge.
  • Add Lighthouse CI with a budget on the median of several runs against a preview URL.
  • Automation does not replace a written manual script in the theme editor: empty states, block limits, color schemes, languages and keyboard use.
  • The linter and budget gate in this lesson are stand-ins; the real tools understand Liquid fully and measure real pages.

Next: Security in Themes