Skip to content
This repository has been archived by the owner on Jul 27, 2024. It is now read-only.

Shopify/theme-check

Folders and files

NameName
Last commit message
Last commit date

Latest commit

357e904 · Apr 14, 2023
Apr 6, 2023
Aug 19, 2021
Jul 14, 2022
Dec 15, 2022
Mar 7, 2023
Sep 27, 2021
Apr 14, 2023
Apr 12, 2021
Apr 10, 2023
Dec 9, 2022
Apr 13, 2021
Apr 14, 2023
Dec 9, 2020
Nov 16, 2022
Sep 7, 2021
Dec 4, 2020
Apr 7, 2021
Nov 10, 2022
Feb 24, 2022
Dec 9, 2022
Nov 16, 2022
Jul 20, 2022
Dec 9, 2022
Dec 9, 2022

Repository files navigation

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