> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Shopify/horizon/llms.txt
> Use this file to discover all available pages before exploring further.

# Theme Check

> Validate and lint your Horizon theme with Theme Check

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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="Install Theme Check VS Code">
    Click "Install" to add the [Theme Check VS Code extension](https://marketplace.visualstudio.com/items?itemName=Shopify.theme-check-vscode).

    Or install manually from the Extensions marketplace:

    1. Press `Cmd/Ctrl + Shift + X`
    2. Search for "Shopify Theme Check"
    3. Click "Install"
  </Step>

  <Step title="Enable real-time validation">
    Once installed, Theme Check automatically validates your Liquid files as you type, showing errors and warnings inline.
  </Step>
</Steps>

### Command Line

Theme Check is included with Shopify CLI:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
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
```

<Note>
  Not all issues can be auto-corrected. Complex problems require manual fixes.
</Note>

### Output Formats

Generate output in different formats:

```bash theme={null}
# 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:

```bash theme={null}
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:**

```liquid theme={null}
{% custom_tag %}
```

**Error:**

```
LiquidTag: Unknown tag 'custom_tag'
```

**Fix:**

Use valid Liquid tags. Check the [Liquid reference](https://shopify.dev/docs/themes/liquid/reference) for available tags.

### ParserBlockingJavaScript

**Problem:**

```liquid theme={null}
<script src="script.js"></script>
```

**Error:**

```
ParserBlockingJavaScript: Avoid parser blocking JavaScript
```

**Fix:**

Use async or defer attributes:

```liquid theme={null}
<script src="script.js" defer></script>
```

### MissingTemplate

**Problem:**

```liquid theme={null}
{{ product.featured_image | img_url: 'large' }}
```

**Error:**

```
MissingTemplate: 'product.featured_image' is deprecated
```

**Fix:**

Use the current API:

```liquid theme={null}
{{ product.featured_media | image_url: width: 1000 }}
```

### UnusedAssign

**Problem:**

```liquid theme={null}
{% assign unused_var = 'value' %}
```

**Error:**

```
UnusedAssign: Variable 'unused_var' is assigned but never used
```

**Fix:**

Remove unused assignments:

```liquid theme={null}
{# Remove the unused assignment #}
```

### SpaceInsideBraces

**Problem:**

```liquid theme={null}
{{product.title}}
```

**Error:**

```
SpaceInsideBraces: Use spaces inside Liquid braces
```

**Fix:**

```liquid theme={null}
{{ product.title }}
```

## Configuration

### Theme Check Configuration File

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

```yaml theme={null}
# .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:

1. Open any `.liquid` file
2. Errors appear as squiggly underlines
3. Hover over errors for details
4. 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:

```json theme={null}
{
  "themeCheck.checkOnSave": true,
  "themeCheck.checkOnChange": true,
  "themeCheck.onlySingleFileChecks": false
}
```

## CI/CD Integration

Horizon runs Theme Check on every commit via [Shopify/theme-check-action](https://github.com/Shopify/theme-check-action).

### GitHub Actions Example

Add Theme Check to your GitHub Actions workflow:

```yaml theme={null}
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:

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Run Before Commits" icon="git">
    Validate your code before committing to catch issues early.
  </Card>

  <Card title="Enable VS Code Extension" icon="code">
    Get real-time feedback while coding for faster development.
  </Card>

  <Card title="Configure for Your Needs" icon="sliders">
    Customize rules in `.theme-check.yml` to match your workflow.
  </Card>

  <Card title="Fix Critical Issues First" icon="exclamation">
    Focus on errors before warnings for maximum impact.
  </Card>
</CardGroup>

### Recommended Workflow

<Steps>
  <Step title="Enable real-time checking">
    Install the VS Code extension for instant feedback while coding.
  </Step>

  <Step title="Run full checks regularly">
    ```bash theme={null}
    shopify theme check
    ```

    Run this before committing code.
  </Step>

  <Step title="Auto-fix when possible">
    ```bash theme={null}
    shopify theme check --auto-correct
    ```

    Let Theme Check fix simple issues automatically.
  </Step>

  <Step title="Address critical issues">
    Fix all errors before deploying to production.
  </Step>
</Steps>

## Troubleshooting

### False Positives

If Theme Check reports incorrect issues:

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

### Performance Issues

If Theme Check is slow:

1. Add large directories to ignore list:
   ```yaml theme={null}
   ignore:
     - node_modules/
     - .git/
   ```
2. Run checks on specific files during development
3. Run full checks only before commits

### Extension Not Working

1. Ensure you're in a valid Shopify theme directory
2. Reload VS Code window
3. Check the Output panel for error messages
4. Reinstall the extension if needed

## Additional Resources

<CardGroup cols={2}>
  <Card title="Theme Check Documentation" icon="book" href="https://shopify.dev/docs/storefronts/themes/tools/theme-check">
    Official Theme Check documentation
  </Card>

  <Card title="Theme Check GitHub" icon="github" href="https://github.com/shopify/theme-check">
    Theme Check source code and issues
  </Card>

  <Card title="Shopify CLI" icon="terminal" href="/development/shopify-cli">
    Learn more about Shopify CLI
  </Card>

  <Card title="Development Workflow" icon="code" href="/development/workflow">
    Best practices for theme development
  </Card>
</CardGroup>

## 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