Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.
Latest commit message
Commit time
August 19, 2021 08:39
September 27, 2021 15:32
December 8, 2020 22:33
September 7, 2021 14:30

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).


  • Ruby 2.7+


Theme Check is available through Homebrew or RubyGems.


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


gem install theme-check


theme-check /path/to/your/theme

# or from /path/to/your/theme

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


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
  - ./path/to/my_custom_check.rb

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

# Enable a custom check
  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.


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

  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.


For guidance on contributing, refer to this doc