Theme Check ✅ - A linter for Themes

Think RuboCop, or eslint, but for Shopify themes.

Theme Check is a command line tool that helps you follow Shopify Themes & Liquid best practices by analyzing the Liquid & JSON inside your theme.

Theme Check is also available inside some code editors.

Supported Checks

Theme Check currently checks for the following:

✅ Liquid syntax errors
✅ JSON syntax errors
✅ Missing snippet & section templates
✅ Unused {% assign ... %}
✅ Unused snippet templates
✅ Template length
✅ Deprecated tags
✅ Unknown tags
✅ Unknown filters
✅ Missing {{ content_for_* }} in theme.liquid
✅ Excessive nesting of snippets
✅ Missing or extra spaces inside {% ... %} and {{ ... }}
✅ Missing default locale file
✅ Unmatching translation keys in locale files
✅ Using unknown translation keys in {{ 'missing_key' | t }}
✅ Using several {% ... %} instead of {% liquid ... %}
✅ Undefined objects
✅ Deprecated filters
✅ Missing theme-check-enable comment

As well as checks that prevent easy to spot performance problems:

✅ Use of parser-blocking JavaScript
✅ Use of non-Shopify domains for assets
✅ Missing width and height attributes on img tags
✅ Too much JavaScript
✅ Too much CSS

For detailed descriptions and configuration options, take a look at the complete list.

With more to come! Suggestions welcome (create an issue).

Requirements

• Ruby 2.7+

Installation

Theme Check is available through Homebrew or RubyGems.

Homebrew

You’ll need to run brew tap first to add Shopify’s third-party repositories to Homebrew.

brew tap shopify/shopify
brew install theme-check

RubyGems

gem install theme-check

Usage

theme-check /path/to/your/theme

# or from /path/to/your/theme
theme-check

Run theme-check --help to get full usage.

Configuration

Add a .theme-check.yml file at the root of your theme to configure:

# If your theme is not using the supported directory structure, provide the root path
# where to find the `templates/`, `sections/`, `snippets/` directories as they would
# be uploaded to Shopify.
root: dist

# It is possible to extend theme-check with custom checks
require:
  - ./path/to/my_custom_check.rb

TemplateLength:
  # Disable some checks
  enabled: false
  # Or configure options
  max_length: 300
  # Or ignore certain paths
  ignore:
    - snippets/icon-*
  # Or change the severity (error|suggestion|style)
  severity: suggestion

# Enable a custom check
MyCustomCheck
  enabled: true

See config/default.yml for available options & defaults.

Disable checks with comments

Use Liquid comments to disable and re-enable all checks for a section of your template:

{% # theme-check-disable %}
{% assign x = 1 %}
{% # theme-check-enable %}

Disable a specific check by including it in the comment:

{% # theme-check-disable UnusedAssign %}
{% assign x = 1 %}
{% # theme-check-enable UnusedAssign %}

Disable multiple checks by including them as a comma-separated list:

{% # theme-check-disable UnusedAssign,SpaceInsideBraces %}
{%assign x = 1%}
{% # theme-check-enable UnusedAssign,SpaceInsideBraces %}

Disable checks for the entire document by placing the comment on the first line:

{% # theme-check-disable SpaceInsideBraces %}
{%assign x = 1%}

Exit Code and --fail-level

Use the --fail-level (default: error) flag to configure the exit code of theme-check. Useful in CI scenarios.

Example:

# Make CI fail on styles warnings, suggestions, and errors
theme-check --fail-level style path_to_theme

# Make CI fail on suggestions, and errors
theme-check --fail-level suggestion path_to_theme

# Make CI fail on errors
theme-check path_to_theme

There are three fail levels:

• error
• suggestion
• style

Exit code meanings:

• 0: Success!
• 1: Your code doesn't pass the checks
• 2: There's a bug in theme-check

If you would like to change the severity of a check, you can do so with the severity attribute. Example:

DeprecateLazysizes:
  enabled: true
  severity: error

Language Server Configurations

• themeCheck.checkOnOpen (default: true) makes it so theme check runs on file open.
• themeCheck.checkOnChange (default: true) makes it so theme check runs on file change.
• themeCheck.checkOnSave (default: true) makes it so theme check runs on file save.
• themeCheck.onlySingleFileChecks (default: false) makes it so we only check the opened files and disable "whole theme" checks (e.g. UnusedSnippet, TranslationKeyExists)

⚠️ Note: Quickfixes only work on a freshly checked file. If any of those configurations are turned off, you will need to rerun theme-check in order to apply quickfixes.

In VS Code, these can be set directly in your settings.json.

Contributing

For guidance on contributing, refer to this doc