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
Anchor link to section titled "Including or excluding check categories"You can include or exclude certain categories of checks using the --category <CATEGORY>
or
--exclude-category <CATEGORY>
flag. This flag accepts the following values:
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
Anchor link to section titled "HTML checks"These checks analyze the content of HTML files.
Check | Severity | Purpose |
---|---|---|
AssetPreload | Suggestion | Encourages preloading of assets using Liquid filters, rather than HTML attributes. |
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
Anchor link to section titled "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
Anchor link to section titled "Liquid checks"These checks analyze the style and validity of Liquid code. Some of these checks support auto-correction using the --auto-correct
flag.
Check | Severity | Purpose | Auto-correction |
---|---|---|---|
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 image_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. | Yes (img_url only) |
DeprecatedGlobalAppBlockType | Error | Makes sure that theme sections are not using the deprecated @global block type to support or render app blocks in a section. |
|
DeprecatedTags | Error | Discourages using deprecated tags 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. | Yes |
MissingAsset | Error | Makes sure that all asset files referenced by the asset_url filter exist. |
|
MissingTemplate | Suggestion | Identifies when a resource is referenced using a render , section , or include tag, but doesn't exist. |
Yes |
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. | Yes |
RequiredLayoutThemeObject | Error | Makes sure that the theme.liquid layout file contains the required {{ content_for_header }} and {{ content_for_layout }} objects. |
Yes |
SchemaJsonFormat | Style | Identifies improperly formatted JSON in {% schema %} tags. |
Yes |
SpaceInsideBraces | Style | Identifies inconsistent spacing inside Liquid tags and variables. | Yes |
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. | Yes |
UnusedSnippet | Suggestion | Identifies snippets that aren't used. | Yes |
Performance checks
Anchor link to section titled "Performance checks"These checks look for common performance issues in theme code.
Check | Severity | Purpose |
---|---|---|
AssetPreload | Suggestion | Encourages preloading of assets using Liquid filters, rather than HTML attributes. |
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 image_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
Anchor link to section titled "Translation checks"These checks ensure that translations are complete. Some of these checks support auto-correction using the --auto-correct
flag.
Check | Severity | Purpose | Auto-correction |
---|---|---|---|
DefaultLocale | Suggestion | Makes sure that the theme has a default locale file. | Yes |
MatchingSchemaTranslations | Suggestion | Identifies missing or additional translations in {% schema %} tags. |
Yes |
MatchingTranslations | Suggestion | Identifies missing or additional translations in locale files. | Yes |
TranslationKeyExists | Error | Identifies references to translations that don't exist. | Yes |