Theme Check and Linting Conventions

You’ve written some Liquid code, and it seems to work. But is it good code? Does it follow Shopify’s best practices? Will it perform well under load? Are there accessibility issues hiding in your markup?

Theme Check answers these questions. It’s Shopify’s official linter for themes: a tool that analyzes your code and reports problems before they reach production.

What Is Theme Check?

Theme Check is a static analysis tool that examines your theme files and flags:

• Syntax errors: Invalid Liquid code
• Performance issues: Slow patterns that hurt page speed
• Accessibility problems: Missing alt text, improper heading structure
• Deprecated features: Old Liquid tags that should be updated
• Best practice violations: Patterns that cause problems

Think of it as a code reviewer that never gets tired and knows Shopify inside out.

Running Theme Check

Theme Check is built into the Shopify CLI.

Basic Usage

Navigate to your theme folder and run:

shopify theme check

Sample Output

Checking 47 files...

sections/header.liquid
  ✗ [error] MissingRequiredTemplateFiles: 'layout/theme.liquid' is missing
  ✗ [warning] ImgWidthAndHeight: Missing width and height attributes on img tag
  ✗ [suggestion] UnusedAssign: 'unused_var' is assigned but never used

Found 1 error, 1 warning, 1 suggestion

Understanding Results

Theme Check reports three severity levels:

Checking Specific Files

Focus on particular files or folders:

# Check one file
shopify theme check sections/header.liquid

# Check a folder
shopify theme check sections/

Output Formats

Get results in different formats:

# JSON (for CI integration)
shopify theme check --output json

# Only show errors (skip warnings/suggestions)
shopify theme check --fail-level error

Common Theme Check Rules

Let’s explore the rules you’ll encounter most often.

Performance Rules

AssetSizeCSS / AssetSizeJS

Flags oversized CSS or JavaScript files:

✗ [warning] AssetSizeCSS: CSS file 'theme.css' exceeds 100KB (currently 156KB)

Fix: Split large files, remove unused code, or minify.

RemoteAsset

Warns about loading assets from external URLs:

<!-- Bad -->
<script src="https://example.com/script.js"></script>

<!-- Good -->
<script src="{{ 'script.js' | asset_url }}" defer></script>

External assets slow down your page and can be unreliable.

ParserBlockingScript

Flags scripts that block page rendering:

<!-- Bad -->
<script src="{{ 'app.js' | asset_url }}"></script>

<!-- Good -->
<script src="{{ 'app.js' | asset_url }}" defer></script>

Liquid Best Practices

UnusedAssign

Warns when you assign a variable but never use it:

{% comment %} Bad - unused variable {% endcomment %}
{% assign unused_var = product.title %}

{% comment %} Good - actually use it {% endcomment %}
{% assign title = product.title %}
<h1>{{ title }}</h1>

DeprecatedTag

Flags old Liquid tags you should replace:

{% comment %} Bad - deprecated {% endcomment %}
{% include 'icon' %}

{% comment %} Good - modern {% endcomment %}
{% render 'icon' %}

LiquidTag

Suggests using the liquid tag for multiple consecutive tags:

{% comment %} Verbose {% endcomment %}
{% assign x = 1 %}
{% assign y = 2 %}
{% assign z = 3 %}

{% comment %} Cleaner {% endcomment %}
{% liquid
  assign x = 1
  assign y = 2
  assign z = 3
%}

Accessibility Rules

ImgWidthAndHeight

Images should have dimensions to prevent layout shift:

{% comment %} Bad {% endcomment %}
<img src="{{ image | image_url }}" alt="Product">

{% comment %} Good {% endcomment %}
<img
  src="{{ image | image_url: width: 400 }}"
  alt="Product"
  width="400"
  height="300"
>

MissingRequiredObjects

Templates must output certain content:

{% comment %} product.liquid must include {% endcomment %}
{{ product.title }}
{{ product.description }}

Template Rules

MissingRequiredTemplateFiles

Every theme needs certain files:

• layout/theme.liquid
• templates/index.json (or .liquid)
• config/settings_schema.json

ValidJSON

JSON files must be valid:

{
  "sections": {
    "main": {
      "type": "main-content"
    }
  },
  "order": ["main"]
}

A single misplaced comma breaks the file.

Configuring Theme Check

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

Basic Configuration

# Ignore specific checks
DeprecatedTag:
  enabled: false

# Adjust thresholds
AssetSizeCSS:
  threshold_in_bytes: 150000 # 150KB instead of default 100KB

# Ignore specific files
ignore:
  - 'templates/customers/*'
  - 'snippets/legacy-*.liquid'

Disabling Rules

Turn off rules that don’t apply to your project:

# We use external fonts intentionally
RemoteAsset:
  enabled: false

# We have large CSS by design
AssetSizeCSS:
  enabled: false

Severity Overrides

Change a rule’s severity:

# Treat as error instead of warning
ImgWidthAndHeight:
  severity: error

# Downgrade to suggestion
UnusedAssign:
  severity: suggestion

Example Configuration

Here’s a practical .theme-check.yml:

# Theme Check Configuration

# Adjust asset size limits for our design system
AssetSizeCSS:
  threshold_in_bytes: 150000

AssetSizeJavaScript:
  threshold_in_bytes: 50000

# We use some external assets intentionally
RemoteAsset:
  enabled: true
  ignore:
    - 'https://fonts.googleapis.com/*'

# Ignore legacy sections we're phasing out
ignore:
  - 'sections/deprecated-*'
  - 'snippets/old-*'

# Don't warn about unused assigns in development
UnusedAssign:
  severity: suggestion

VS Code Integration

Get real-time feedback while you code.

Installing the Extension

1. Open VS Code
2. Go to Extensions (Cmd/Ctrl + Shift + X)
3. Search for “Shopify Liquid”
4. Install the official Shopify extension

Or from terminal:

code --install-extension Shopify.theme-check-vscode

What You Get

• Inline errors: See problems as you type
• Hover information: Details about Liquid objects and filters
• Auto-complete: Suggestions for Liquid tags and objects
• Format on save: Automatic code formatting

Extension Settings

Configure in VS Code settings (Cmd/Ctrl + ,):

{
  "shopifyLiquid.formatterDevPreview": true,
  "themeCheck.checkOnSave": true,
  "themeCheck.checkOnOpen": true
}

Integrating with CI/CD

Run Theme Check automatically on every push.

GitHub Actions Example

Create .github/workflows/theme-check.yml:

name: Theme Check

on: [push, pull_request]

jobs:
  theme-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Shopify CLI
        run: npm install -g @shopify/cli @shopify/theme

      - name: Run Theme Check
        run: shopify theme check --fail-level error

Exit Codes

Theme Check returns different exit codes for CI:

• 0: No errors
• 1: Errors found
• 2: Configuration error

Use --fail-level to control when checks fail:

# Only fail on errors
shopify theme check --fail-level error

# Fail on warnings too
shopify theme check --fail-level warning

Fixing Common Violations

Let’s walk through fixes for the most common issues.

Missing Image Dimensions

Problem:

<img src="{{ product.featured_image | image_url: width: 400 }}" alt="{{ product.title }}">

Solution:

<img
  src="{{ product.featured_image | image_url: width: 400 }}"
  alt="{{ product.title }}"
  width="400"
  height="{{ 400 | divided_by: product.featured_image.aspect_ratio | round }}"
  loading="lazy"
>

Deprecated include Tag

Problem:

{% include 'product-card', product: product %}

Solution:

{% render 'product-card', product: product %}

Note: render has different scoping rules. Variables from the parent don’t automatically pass through.

Parser-Blocking JavaScript

Problem:

{{ 'app.js' | asset_url | script_tag }}

Solution:

<script src="{{ 'app.js' | asset_url }}" defer></script>

Missing Required Schema

Problem:

Section without a schema block.

Solution:

<section>
  <!-- content -->
</section>

{% schema %}
{
  "name": "Section Name",
  "settings": []
}
{% endschema %}

Unused Variables

Problem:

{% assign product_title = product.title %}
{% assign product_price = product.price %}
<h2>{{ product.title }}</h2>

Solution:

Remove unused assignments or use them:

{% assign product_title = product.title %}
<h2>{{ product_title }}</h2>

Theme Check in Your Workflow

Before Every Commit

Make it a habit:

# Check for errors
shopify theme check

# If clean, commit
git add .
git commit -m "Add new feature"

Before Every Push to Production

# Final check
shopify theme check --fail-level warning

# If clean, push
shopify theme push --theme [production-id]

During Code Review

When reviewing others’ code:

1. Pull their branch
2. Run shopify theme check
3. Ensure no new violations

Quick Reference

What’s Next?

You now have a complete development environment:

• ✅ Development store and Partners account
• ✅ Shopify CLI for local development
• ✅ A minimal sandbox theme
• ✅ Theme syncing mastery
• ✅ Git for version control
• ✅ Theme Check for quality assurance

You’re ready to dive into Liquid! Continue to Module 3 where we’ll explore Liquid objects, filters, and the building blocks of theme development.