Theme Check - Horizon

Theme Check is a linter and validator for Shopify themes that helps you write better Liquid code by catching errors and enforcing best practices.

Overview

Theme Check analyzes your theme files and reports:

Syntax errors: Invalid Liquid syntax
Performance issues: Code that may slow down your theme
Accessibility problems: Missing or incorrect accessibility attributes
Best practice violations: Code that doesn’t follow Shopify’s recommendations
Translation issues: Missing or incorrect translation keys

Installation Methods

VS Code Extension (Recommended)

Horizon includes Theme Check in its list of recommended VS Code extensions.

Open Horizon in VS Code

When you open the Horizon theme in VS Code for the first time, you’ll see a prompt to install recommended extensions.

Install Theme Check VS Code

Click “Install” to add the Theme Check VS Code extension.Or install manually from the Extensions marketplace:

Press Cmd/Ctrl + Shift + X
Search for “Shopify Theme Check”
Click “Install”

Enable real-time validation

Once installed, Theme Check automatically validates your Liquid files as you type, showing errors and warnings inline.

Command Line

Theme Check is included with Shopify CLI:

shopify theme check

No additional installation required if you have Shopify CLI installed.

Running Theme Check

Basic Usage

Run Theme Check on your entire theme:

shopify theme check

Output with no issues:

Checking theme...

✓ No issues found

Theme check complete!

Output with issues:

Checking theme...

sections/header.liquid:45:12
  LiquidTag: Unknown tag 'custom_tag'
  https://shopify.dev/docs/themes/liquid/reference

templates/product.liquid:23:8
  ParserBlockingJavaScript: Avoid parser blocking JavaScript
  Use async or defer attributes on script tags

snippets/product-card.liquid:67:4
  MissingTemplate: Template variable 'product.featured_image' is deprecated
  Use 'product.featured_media' instead

3 issues found

Check Specific Files

Validate specific files or directories:

# Single file
shopify theme check templates/product.liquid

# Directory
shopify theme check sections/

# Multiple files
shopify theme check templates/product.liquid sections/header.liquid

Auto-Correct Issues

Automatically fix issues that can be corrected:

shopify theme check --auto-correct

Output:

Checking theme...

templates/product.liquid:15:4
  ✓ Fixed: SpaceInsideBraces

snippets/icon.liquid:8:2
  ✓ Fixed: UnusedAssign

2 issues auto-corrected

Not all issues can be auto-corrected. Complex problems require manual fixes.

Output Formats

Generate output in different formats:

# JSON format (useful for CI/CD)
shopify theme check --output json

# Example output
# {
#   "errors": [],
#   "warnings": [
#     {
#       "path": "templates/product.liquid",
#       "line": 23,
#       "column": 8,
#       "message": "Avoid parser blocking JavaScript"
#     }
#   ]
# }

List Available Checks

View all available Theme Check rules:

shopify theme check --list

Output:

Available checks:

- AssetPreload
- AssetSizeCSS
- AssetSizeJavaScript
- ContentForHeaderModification
- DeprecatedFilter
- DeprecatedTag
- ImgLazyLoading
- LiquidTag
- MatchingTranslations
- MissingTemplate
- ParserBlockingJavaScript
- RemoteAsset
- SpaceInsideBraces
- SyntaxError
- UnusedAssign
- ValidHTMLTranslation
...

Common Issues and Fixes

LiquidTag Errors

Problem:

{% custom_tag %}

Error:

LiquidTag: Unknown tag 'custom_tag'

Fix: Use valid Liquid tags. Check the Liquid reference for available tags.

ParserBlockingJavaScript

Problem:

<script src="script.js"></script>

Error:

ParserBlockingJavaScript: Avoid parser blocking JavaScript

Fix: Use async or defer attributes:

<script src="script.js" defer></script>

MissingTemplate

Problem:

{{ product.featured_image | img_url: 'large' }}

Error:

MissingTemplate: 'product.featured_image' is deprecated

Fix: Use the current API:

{{ product.featured_media | image_url: width: 1000 }}

UnusedAssign

Problem:

{% assign unused_var = 'value' %}

Error:

UnusedAssign: Variable 'unused_var' is assigned but never used

Fix: Remove unused assignments:

{# Remove the unused assignment #}

SpaceInsideBraces

Problem:

{{product.title}}

Error:

SpaceInsideBraces: Use spaces inside Liquid braces

Fix:

{{ product.title }}

Configuration

Theme Check Configuration File

Create a .theme-check.yml file in your theme root to customize rules:

# .theme-check.yml

# Disable specific checks
ParserBlockingJavaScript:
  enabled: false

# Configure severity levels
AssetSizeCSS:
  severity: warning
  threshold_in_bytes: 100000

# Ignore specific files
ignore:
  - node_modules/
  - dist/

Severity Levels

Theme Check uses three severity levels:

error: Critical issues that should be fixed
warning: Issues that should be addressed but aren’t critical
info: Suggestions for improvement

VS Code Integration

Real-Time Validation

With the VS Code extension installed:

Open any .liquid file
Errors appear as squiggly underlines
Hover over errors for details
Click “Quick Fix” for auto-correct suggestions

Extension Features

Syntax highlighting: Enhanced Liquid syntax highlighting
Auto-completion: IntelliSense for Liquid tags and filters
Hover documentation: Inline documentation for Liquid elements
Go to definition: Jump to snippet and section definitions
Format on save: Auto-format Liquid files

Extension Settings

Configure the extension in VS Code settings:

{
  "themeCheck.checkOnSave": true,
  "themeCheck.checkOnChange": true,
  "themeCheck.onlySingleFileChecks": false
}

CI/CD Integration

Horizon runs Theme Check on every commit via Shopify/theme-check-action.

GitHub Actions Example

Add Theme Check to your GitHub Actions workflow:

name: Theme Check

on: [push, pull_request]

jobs:
  theme-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Run Theme Check
        uses: shopify/theme-check-action@v1
        with:
          path: '.'

Command Line for CI

Run Theme Check in CI pipelines:

# Exit with error code if issues found
shopify theme check --fail-level error

# Output JSON for parsing
shopify theme check --output json > theme-check-results.json

Best Practices

Run Before Commits

Validate your code before committing to catch issues early.

Enable VS Code Extension

Get real-time feedback while coding for faster development.

Configure for Your Needs

Customize rules in .theme-check.yml to match your workflow.

Fix Critical Issues First

Focus on errors before warnings for maximum impact.

Recommended Workflow

Enable real-time checking

Install the VS Code extension for instant feedback while coding.

Run full checks regularly

shopify theme check

Run this before committing code.

Auto-fix when possible

shopify theme check --auto-correct

Let Theme Check fix simple issues automatically.

Address critical issues

Fix all errors before deploying to production.

Troubleshooting

False Positives

If Theme Check reports incorrect issues:

Update Shopify CLI to the latest version
Check if the issue is a known limitation
Add exceptions in .theme-check.yml if necessary

Performance Issues

If Theme Check is slow:

Add large directories to ignore list:
```
ignore:
  - node_modules/
  - .git/
```
Run checks on specific files during development
Run full checks only before commits

Extension Not Working

Ensure you’re in a valid Shopify theme directory
Reload VS Code window
Check the Output panel for error messages
Reinstall the extension if needed

Additional Resources

Theme Check Documentation

Official Theme Check documentation

Theme Check GitHub

Theme Check source code and issues

Shopify CLI

Learn more about Shopify CLI

Development Workflow

Best practices for theme development

Next Steps

Now that you understand Theme Check, explore:

Run shopify theme check on your theme
Install the VS Code extension for real-time validation
Configure .theme-check.yml for your project
Integrate Theme Check into your CI/CD pipeline

Overview

Core Concepts

Development

Customization

Features

​Overview

​Installation Methods

​VS Code Extension (Recommended)

​Command Line

​Running Theme Check

​Basic Usage

​Check Specific Files

​Auto-Correct Issues

​Output Formats

​List Available Checks

​Common Issues and Fixes

​LiquidTag Errors

​ParserBlockingJavaScript

​MissingTemplate

​UnusedAssign

​SpaceInsideBraces

​Configuration

​Theme Check Configuration File

​Severity Levels

​VS Code Integration

​Real-Time Validation

​Extension Features

​Extension Settings

​CI/CD Integration

​GitHub Actions Example

​Command Line for CI

​Best Practices

Run Before Commits

Enable VS Code Extension

Configure for Your Needs

Fix Critical Issues First

​Recommended Workflow

​Troubleshooting

​False Positives

​Performance Issues

​Extension Not Working

​Additional Resources

Theme Check Documentation

Theme Check GitHub

Shopify CLI

Development Workflow

​Next Steps

Build docs developers (and LLMs) love

Overview

Installation Methods

VS Code Extension (Recommended)

Command Line

Running Theme Check

Basic Usage

Check Specific Files

Auto-Correct Issues

Output Formats

List Available Checks

Common Issues and Fixes

LiquidTag Errors

ParserBlockingJavaScript

MissingTemplate

UnusedAssign

SpaceInsideBraces

Configuration

Theme Check Configuration File

Severity Levels

VS Code Integration

Real-Time Validation

Extension Features

Extension Settings

CI/CD Integration

GitHub Actions Example

Command Line for CI

Best Practices

Recommended Workflow

Troubleshooting

False Positives

Performance Issues

Extension Not Working

Additional Resources

Next Steps