Checks reference

You can run the following checks as part of Theme Check. Each check identifies a specific error or a place in your code where a best practice is not being followed.

Checks are grouped by category to help you to understand their purpose. Some checks are in multiple categories.

To learn more about the check and its options, click on the name of the check.

Including or excluding check categories

You can include or exclude certain categories of checks using the --category <CATEGORY> or --exclude-category <CATEGORY> flag.

For example, to run only Liquid checks for a theme, use the command shopify theme check --category liquid. To disable translation checks, use the command shopify theme check --exclude-category translation.

You can specify multiple categories using multiple instances of the flag:

HTML checks

These checks analyze the content of HTML files.

Check Severity Purpose
AssetSizeCSS Error Prevents themes from using CSS files larger than the configured threshold.
AssetSizeJavaScript Error Prevents using theme JavaScript files and external scripts with a compressed size greater than the configured threshold.
DeprecateBgsizes Suggestion Discourages use of the bgset extension instead of the image-set attribute for loading background images.
DeprecateLazysizes Suggestion Discourages use of the lazysizes library for lazy loading images, iframes, and scripts.
HtmlParsingError Error Reports errors preventing the HTML from being parsed and analyzed by Theme Check.
ImgLazyLoading Suggestion Suggests lazy loading for images to increase performance.
ImgWidthAndHeight Error Enforces setting the width and height attributes on img tags.
ParserBlockingJavaScript Error Identifies script tags that don't have defer or async attributes, avoiding parser-blocking JavaScript.
RemoteAsset Suggestion Discourages the use of third party domains for hosting assets.

JSON checks

These checks analyze the content and structure of JSON files and syntax.

Check Severity Purpose
ValidJson Error Identifies invalid JSON files in themes.
ValidSchema Suggestion Identifies invalid JSON in {% schema %} tags.
ValidHTMLTranslation Suggestion Identifies invalid HTML inside translations.

Liquid checks

These checks analyze the style and validity of Liquid code.

Check Severity Purpose
AppBlockValidTags Error Identifies forbidden Liquid tags in theme app extension app block and app embed block code.
AssetSizeCSSStyleSheetTag Error Prevents themes from referencing CSS files larger than the configured threshold using a Liquid stylesheet tag.
AssetUrlFilters Error Encourages the use of asset_url or img_url filters to serve assets.
ContentForHeaderModification Error Identifies code that tries to parse content_for_header.
ConvertIncludeToRender Suggestion Discourages using the deprecated include tag instead of the render tag.
DeprecatedFilter Suggestion Discourages using deprecated filters in themes.
LiquidTag Suggestion Recommends using {% liquid ... %} if four or more consecutive Liquid tags ({% ... %}) are found.
MissingEnableComment Error Makes sure that when theme-check-disable is used in the middle of a template, the corresponding theme-check-enable comment is also present.
MissingRequiredTemplateFiles Error Makes sure that all template files required for the Shopify Theme Store are present.
MissingTemplate Suggestion Identifies when a resource is referenced using a render, section, or include tag, but doesn't exist.
NestedSnippet Suggestion Reports deeply nested render tags or include tags.
ParserBlockingScriptTag Error Identifies the use of the script_tag filter.
RequiredDirectories Error Makes sure that all template files required for the Shopify Theme Store are present.
RequiredLayoutThemeObject Error Makes sure that the theme.liquid layout file contains the required {{ content_for_header }} and {{ content_for_layout }} objects.
SpaceInsideBraces Style Identifies inconsistent spacing inside Liquid tags and variables.
SyntaxError Error Identifies Liquid syntax errors.
TemplateLength Suggestion Identifies large Liquid template files.
UndefinedObject Error Identifies references to undefined Liquid objects.
UnknownFilter Error Identifies references to unknown Liquid filters.
UnusedAssign Suggestion Identifies variable definitions that aren't used.
UnusedSnippet Suggestion Identifies snippets that aren't used.

Performance checks

These checks look for common performance issues in theme code.

Check Severity Purpose
AssetSizeAppBlockCSS Error Prevents theme app extensions from using CSS files larger than the configured threshold.
AssetSizeAppBlockJavascript Error Prevents theme app extensions from using JavaScript files and external scripts with a compressed size larger than the configured threshold.
AssetSizeCSS Error Prevents themes from using CSS files larger than the configured threshold.
AssetSizeCSSStyleSheetTag Error Prevents themes from referencing CSS files larger than the configured threshold using a Liquid stylesheet tag.
AssetSizeJavaScript Error Prevents using theme JavaScript files and external scripts with a compressed size greater than the configured threshold.
AssetUrlFilters Error Encourages the use of asset_url or img_url filters to serve assets.
DeprecateBgsizes Suggestion Discourages use of the bgset extension instead of the image-set attribute for loading background images.
DeprecateLazysizes Suggestion Discourages use of the lazysizes library for lazy loading images, iframes, and scripts.
ImgLazyLoading Suggestion Suggests lazy loading for images to increase performance.
ImgWidthAndHeight Error Enforces setting the width and height attributes on img tags.
PaginationSize Suggestion Ensures that objects are paginated with performant sizes so too many objects are not loaded at once.
ParserBlockingJavaScript Error Identifies script tags that don't have defer or async attributes.
ParserBlockingScriptTag Error Identifies the use of the script_tag filter that isn't wrapped in a script tag with defer or async attributes.
RemoteAsset Suggestion Discourages use of third party domains for hosting assets.

Translation checks

These checks ensure that translations are complete.

Check Severity Purpose
DefaultLocale Suggestion Makes sure that the theme has a default locale file.
MatchingSchemaTranslations Suggestion Identifies missing or additional translations in {% schema %} tags.
MatchingTranslations Suggestion Identifies missing or additional translations in locale files.
TranslationKeyExists Error Identifies references to translations that don't exist.