theme-check 0.3.2 → 0.7.0

data/docs/checks/CHECK_DOCS_TEMPLATE.md

@@ -0,0 +1,47 @@
+# Check Title (`CheckClassName`)
+
+A brief paragraph explaining why the check exists.
+
+## Check Details
+
+This check is aimed at eliminating ...
+
+:-1: Examples of **incorrect** code for this check:
+
+```liquid
+```
+
+:+1: Examples of **correct** code for this check:
+
+```liquid
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+CheckClassName:
+  enabled: true
+  some_option: 10
+```
+
+### `some_option`
+
+The `some_option` option (Default: `10`) determines ...
+
+## When Not To Use It
+
+If you don't want to ..., then it's safe to disable this rule.
+
+## Version
+
+This check has been introduced in Theme Check X.X.X.
+
+## Resources
+
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[codesource]: /lib/theme_check/checks/check_class_name.rb
+[docsource]: /docs/checks/check_class_name.md

data/docs/checks/asset_size_css.md

@@ -0,0 +1,52 @@
+# Prevent Large CSS bundles (`AssetSizeCSS`)
+
+This rule exists to prevent large CSS bundles (for speed).
+
+## Check Details
+
+This rule disallows the use of too much CSS in themes, as configured by `threshold_in_bytes`.
+
+:-1: Examples of **incorrect** code for this check:
+```liquid
+<!-- Here, assets/theme.css is **greater** than `threshold_in_bytes` compressed. -->
+{{ 'theme.css' | asset_url | stylesheet_tag }}
+```
+
+:+1: Example of **correct** code for this check:
+```liquid
+<!-- Here, assets/theme.css is **less** than `threshold_in_bytes` compressed. -->
+{{ 'theme.css' | asset_url | stylesheet_tag }}
+```
+
+## Check Options
+
+The default configuration is the following.
+
+```yaml
+AssetSizeCSS:
+  enabled: false
+  threshold_in_bytes: 100_000
+```
+
+### `threshold_in_bytes`
+
+The `threshold_in_bytes` option (default: `100_000`) determines the maximum allowed compressed size in bytes that a single CSS file can take.
+
+This includes theme and remote stylesheets.
+
+## When Not To Use It
+
+This rule is safe to disable.
+
+## Version
+
+This check has been introduced in Theme Check 0.6.0.
+
+## Resources
+
+- [The Performance Inequality Gap](https://infrequently.org/2021/03/the-performance-inequality-gap/)
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[codesource]: /lib/theme_check/checks/asset_size_css.rb
+[docsource]: /docs/checks/asset_size_css.md

data/docs/checks/asset_size_javascript.md

@@ -0,0 +1,79 @@
+# Prevent JavaScript Abuse on Server Rendered Themes (`AssetSizeJavaScript`)
+
+For server rendered pages, it is an anti-pattern to execute large JavaScript bundles on every navigation.
+
+This doesn't mean they don't have a reason to exist. For instance, chat widgets are mini applications embedded inside web pages. Designing such an app with server rendered updates would be absurd. However, if only 10% of the users interact with the chat widget, the other 90% should not have to execute the entire bundle on every page load.
+
+The natural solution to this problem is to implement the chat widget using the [Import on Interaction Pattern][ioip].
+
+## Check Details
+
+This rule disallows the use of theme JavaScript files and external scripts to have a compressed size greater than a configured `threshold_in_bytes`.
+
+:-1: Examples of **incorrect** code for this check:
+```liquid
+<!-- Here assets/chat-widget.js is more than 10KB gzipped. -->
+<script src="{{ 'chat-widget.js' | asset_url }}" defer></script>
+
+<!-- The use of jQuery is discouraged in themes -->
+<script src="https://code.jquery.com/jquery-3.6.0.min.js" defer></script>
+```
+
+:+1: Example of **correct** code for this check:
+```liquid
+<script>
+  const chatWidgetButton = document.getElementById('#chat-widget')
+
+  chatWidgetButton.addEventListener('click', e => {
+    e.preventDefault();
+    import("{{ 'chat-widget.js' | asset_url }}")
+      .then(module => module.default)
+      .then(ChatWidget => ChatWidget.init())
+      .catch(err => {
+        console.error(err);
+      });
+  });
+</script>
+```
+
+## Check Options
+
+The default configuration is the following.
+
+```yaml
+AssetSizeJavaScript:
+  enabled: false
+  threshold_in_bytes: 10000
+```
+
+### `threshold_in_bytes`
+
+The `threshold_in_bytes` option (default: `10000`) determines the maximum allowed compressed size in bytes that a single JavaScript file can take.
+
+This includes theme and remote scripts.
+
+## When Not To Use It
+
+When you can't do anything about it, it is preferable to disable this rule using the comment syntax:
+
+```
+{% comment %}theme-check-disable AssetSizeJavaScript{% endcomment %}
+<script src="https://code.jquery.com/jquery-3.6.0.min.js" defer></script>
+{% comment %}theme-check-enable AssetSizeJavaScript{% endcomment %}
+```
+
+This makes disabling the rule an explicit affair and shows that the code is smelly.
+
+## Version
+
+This check has been introduced in Theme Check 0.5.0.
+
+## Resources
+
+- [The Import On Interaction Pattern][ioip]
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[ioip]: https://addyosmani.com/blog/import-on-interaction/
+[codesource]: /lib/theme_check/checks/asset_size_javascript.rb
+[docsource]: /docs/checks/asset_size_javascript.md

data/docs/checks/convert_include_to_render.md

@@ -0,0 +1,48 @@
+# Discourage the use of `include` (`ConvertIncludeToRender`)
+
+The `include` tag is [deprecated][deprecated]. This tag exists to enforce the use of the `render` tag instead of `include`.
+
+The `include` tag works similarly to the `render` tag, but it lets the code inside of the snippet to access and overwrite the variables within its parent template. The `include` tag has been deprecated because the way that it handles variables reduces performance and makes theme code harder to both read and maintain.
+
+## Check Details
+
+This check is aimed at eliminating the use of `include` tags.
+
+:-1: Examples of **incorrect** code for this check:
+
+```liquid
+{% include 'snippet' %}
+```
+
+:+1: Examples of **correct** code for this check:
+
+```liquid
+{% render 'snippet' %}
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+ConvertIncludeToRender:
+  enabled: true
+```
+
+## When Not To Use It
+
+It is discouraged to disable this rule.
+
+## Version
+
+This check has been introduced in Theme Check 0.1.0.
+
+## Resources
+
+- [Deprecated Tags Reference][deprecated]
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[deprecated]: https://shopify.dev/docs/themes/liquid/reference/tags/deprecated-tags#include
+[codesource]: /lib/theme_check/checks/convert_include_to_render.rb
+[docsource]: /docs/checks/convert_include_to_render.md

data/docs/checks/default_locale.md

@@ -0,0 +1,46 @@
+# Ensure theme has a default locale (`DefaultLocale`)
+
+This check makes sure the theme has a default translation file.
+
+## Check Details
+
+This check makes sure a theme has a default locale.
+
+:-1: Example of **incorrect** theme for this check:
+
+```
+locales/
+├── en.json
+├── fr.json
+└── zh-TW.json
+```
+
+:+1: Example of **correct** theme for this check:
+
+```
+locales/
+├── en.default.json  # a default translation file is required
+├── fr.json
+└── zh-TW.json
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+DefaultLocale:
+  enabled: true
+```
+
+## Version
+
+This check has been introduced in Theme Check 0.1.0.
+
+## Resources
+
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[codesource]: /lib/theme_check/checks/default_locale.rb
+[docsource]: /docs/checks/default_locale.md

data/docs/checks/deprecated_filter.md

@@ -0,0 +1,46 @@
+# Discourage use of deprecated filters (`DeprecatedFilter`)
+
+This check discourages the use of [deprecated filters][deprecated].
+
+## Check Details
+
+This check is aimed at eliminating deprecated filters.
+
+:-1: Example of **incorrect** code for this check:
+
+```liquid
+.site-footer p {
+  color: {{ settings.color_name | hex_to_rgba: 0.5 }};
+}
+```
+
+:+1: Example of **correct** code for this check:
+
+```liquid
+.site-footer p {
+  color: {{ settings.color_name | color_modify: 'alpha', 0.5 }};
+}
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+DeprecatedFilter:
+  enabled: true
+```
+
+## Version
+
+This check has been introduced in Theme Check 0.2.0.
+
+## Resources
+
+- [Deprecated Filters Reference][deprecated]
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[deprecated]: https://shopify.dev/docs/themes/liquid/reference/filters/deprecated-filters
+[codesource]: /lib/theme_check/checks/deprecated_filter.rb
+[docsource]: /docs/checks/deprecated_filter.md

data/docs/checks/img_width_and_height.md

@@ -0,0 +1,79 @@
+# Width and height attributes on image tags (`ImgWidthAndHeight`)
+
+This check exists to prevent [cumulative layout shift][cls] (CLS) in themes.
+
+The absence of `width` and `height` attributes on an `img` tag prevents the browser from knowing the aspect ratio of the image before it is downloaded. Unless another technique is used to allocate space, the browser will consider the image to be of height 0 until it is loaded.
+
+This has numerous nefarious implications:
+
+1. [This causes layout shift as images start appearing one after the other.][codepenshift] Text starts flying down the page as the image pushes it down.
+2. [This breaks lazy loading.][codepenlazy] When all images have a height of 0px, every image is inside the viewport. And when everything is in the viewport, everything gets loaded. There's nothing lazy about it!
+
+The fix is easy. Make sure the `width` and `height` attribute are set on the `img` tag and that the CSS width of the image is set.
+
+Note: The width and height attributes of an image do not have  units.
+
+## Check Details
+
+This check is aimed at eliminating content layout shift in themes by enforcing the use of the `width` and `height` attributes on `img` tags.
+
+:-1: Examples of **incorrect** code for this check:
+
+```liquid
+<img alt="cat" src="cat.jpg">
+<img alt="cat" src="cat.jpg" width="100px" height="100px">
+<img alt="{{ image.alt }}" src="{{ image.src }}">
+```
+
+:+1: Examples of **correct** code for this check:
+
+```liquid
+<img alt="cat" src="cat.jpg" width="100" height="200">
+<img
+  alt="{{ image.alt }}"
+  src="{{ image.src }}"
+  width="{{ image.width }}"
+  height="{{ image.height }}"
+>
+```
+
+**NOTE:** The CSS `width` of the `img` should _also_ be set for the image to be responsive.
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+ImgWidthAndHeight:
+  enabled: true
+```
+
+## When Not To Use It
+
+There are some cases where you can avoid content-layout shift without needing the width and height attributes:
+
+- When the aspect-ratio of the displayed image should be independent of the uploaded image. In those cases, the solution is still the padding-top hack with an `overflow: hidden container`.
+- When you are happy with the padding-top hack.
+
+In those cases, it is fine to disable this check with the comment. 
+
+It is otherwise unwise to disable this check, since it would negatively impact the mobile search ranking of the merchants using your theme.
+
+## Version
+
+This check has been introduced in Theme Check 0.6.0.
+
+## Resources
+
+- [Cumulative Layout Shift Reference][cls]
+- [Codepen illustrating the impact of width and height on layout shift][codepenshift]
+- [Codepen illustrating the impact of width and height on lazy loading][codepenlazy]
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[cls]: https://web.dev/cls/
+[codepenshift]: https://codepen.io/charlespwd/pen/YzpxPEp?editors=1100
+[codepenlazy]: https://codepen.io/charlespwd/pen/abZmqXJ?editors=0111
+[aspect-ratio]: https://caniuse.com/mdn-css_properties_aspect-ratio
+[codesource]: /lib/theme_check/checks/img_aspect_ratio.rb
+[docsource]: /docs/checks/img_aspect_ratio.md

data/docs/checks/liquid_tag.md

@@ -0,0 +1,65 @@
+# Encourage use of liquid tag for consecutive statements (LiquidTag)
+
+Recommends using `{% liquid ... %}` if 4 or more consecutive liquid tags (`{% ... %}`) are found.
+
+## Check Details
+
+This check is aimed at eliminating repetitive tag markers (`{%` and `%}`) in theme files.
+
+:-1: Example of **incorrect** code for this check:
+
+```liquid
+{% if collection.image.size != 0 %}
+{%   assign collection_image = collection.image %}
+{% elsif collection.products.first.size != 0 and collection.products.first.media != empty %}
+{%   assign collection_image = collection.products.first.featured_media.preview_image %}
+{% else %}
+{%   assign collection_image = nil %}
+{% endif %}
+```
+
+:+1: Example of **correct** code for this check:
+
+```liquid
+{%- liquid
+  if collection.image.size != 0
+    assign collection_image = collection.image
+  elsif collection.products.first.size != 0 and collection.products.first.media != empty
+    assign collection_image = collection.products.first.featured_media.preview_image
+  else
+    assign collection_image = nil
+  endif
+-%}
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+LiquidTag:
+  enabled: true
+  min_consecutive_statements: 4
+```
+
+### `min_consecutive_statements`
+
+The `min_consecutive_statements` option (Default: `4`) determines the maximum (inclusive) number of consecutive statements before the check recommends a refactor.
+
+## When Not To Use It
+
+It's safe to disable this rule.
+
+## Version
+
+This check has been introduced in Theme Check 0.1.0.
+
+## Resources
+
+- [`{% liquid %}` Tag Reference][liquid]
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[liquid]: https://shopify.dev/docs/themes/liquid/reference/tags/theme-tags#liquid
+[codesource]: /lib/theme_check/checks/liquid_tag.rb
+[docsource]: /docs/checks/liquid_tag.md