theme-check 0.3.0 → 0.5.0

data/docs/checks/parser_blocking_javascript.md

@@ -0,0 +1,97 @@
+# Discourage use of parser-blocking JavaScript (`ParserBlockingJavaScript`)
+
+The `defer` or `async` attributes are extremely important on script tags. When neither of those attributes are used, a script tag will block the construction and rendering of the DOM until the script is _loaded_, _parsed_ and _executed_. It also creates congestion on the Network, messes with the resource priorities and significantly delays the rendering of the page.
+
+Considering that JavaScript on Shopify themes should always be used to progressively _enhance_ the experience of the site, themes should never make use of parser-blocking script tags.
+
+As a general rule, use `defer` if the order of execution matters, `async` otherwise. When in doubt, choose either one and get 80/20 of the benefits.
+
+## Check Details
+
+This check is aimed at eliminating parser-blocking JavaScript on themes.
+
+:-1: Examples of **incorrect** code for this check:
+
+```liquid
+<!-- The script_tag filter outputs a parser-blocking script -->
+{{ 'app-code.js' | asset_url | script_tag }}
+
+<!-- jQuery is typically loaded synchronously because inline scripts depend on $, don't do that. -->
+<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
+...
+<button id="thing">Click me!</button>
+<script>
+  $('#thing').click(() => {
+    alert('Oh. Hi Mark!');
+  });
+</script>
+```
+
+:+1: Examples of **correct** code for this check:
+
+```liquid
+<!-- Good. Using the asset_url filter + defer -->
+<script src="{{ 'theme.js' | asset_url }}" defer><script>
+
+<!-- Also good. Using the asset_url filter + async -->
+<script src="{{ 'theme.js' | asset_url }}" async><script>
+
+<!-- Better than synchronous jQuery -->
+<script src="https://code.jquery.com/jquery-3.6.0.min.js" defer><script>
+...
+<button id="thing">Click me!</button>
+<script>
+  // Because we're using `defer`, jQuery is guaranteed to
+  // be loaded when DOMContentLoaded fires. This technique
+  // could be used as a first step to refactor an old theme
+  // that inline depends on jQuery.
+  document.addEventListener('DOMContentLoaded', () => {
+    $('#thing').click(() => {
+      alert('Oh. Hi Mark!');
+    });
+  });
+</script>
+
+<!-- Even better. Web Native (no jQuery). -->
+<button id="thing">Click Me</button>
+<script>
+  const button = document.getElementById('thing');
+  button.addEventListener('click', () => {
+    alert('Oh. Hi Mark!');
+  });
+</script>
+
+<!-- Best -->
+<script src="{{ 'theme.js' | asset_url }}" defer></script>
+...
+<button id="thing">Click Me</button>
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+ParserBlockingJavaScript:
+  enabled: true
+```
+
+## When Not To Use It
+
+This should only be turned off with the `theme-check-disable` comment when there's no better way to accomplish what you're doing than with a parser-blocking script.
+
+It is discouraged to turn this rule off.
+
+## Version
+
+This check has been introduced in Theme Check 0.3.0.
+
+## Resources
+
+- [Lighthouse Render-Blocking Resources Audit][render-blocking]
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[render-blocking]: https://web.dev/render-blocking-resources/
+[codesource]: /lib/theme_check/checks/parser_blocking_javascript.rb
+[docsource]: /docs/checks/parser_blocking_javascript.md

data/docs/checks/required_directories.md

@@ -0,0 +1,25 @@
+# Prevent missing directories (`RequiredDirectories`)
+
+This check exists to warn theme developers about missing required directories in their structure.
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+RequiredDirectories:
+  enabled: true
+```
+
+## Version
+
+This check has been introduced in Theme Check 0.1.0.
+
+## Resources
+
+- [Shopify Theme File Structure](https://shopify.dev/tutorials/develop-theme-files)
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[codesource]: /lib/theme_check/checks/required_directories.rb
+[docsource]: /docs/checks/required_directories.md

data/docs/checks/required_layout_theme_object.md

@@ -0,0 +1,28 @@
+# Prevent missing required objects in theme.liquid (`RequiredLayoutThemeObject`)
+
+## Check Details
+
+This check prevents missing `{{ content_for_header }}` and `{{ content_for_layout }}` objects in `layout/theme.liquid`.
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+RequiredLayoutThemeObject:
+  enabled: true
+```
+
+## Version
+
+This check has been introduced in Theme Check 0.1.0.
+
+## Resources
+
+- [Shopify theme.liquid requirements][themeliquid]
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[codesource]: /lib/theme_check/checks/required_layout_theme_object.rb
+[docsource]: /docs/checks/required_layout_theme_object.md
+[themeliquid]: https://shopify.dev/docs/themes/theme-templates/theme-liquid

data/docs/checks/space_inside_braces.md

@@ -0,0 +1,63 @@
+# Ensure consistent spacing inside Liquid tags and variables (`SpaceInsideBraces`)
+
+Warns against inconsistent spacing inside liquid tags and variables.
+
+## Check Details
+
+This check is aimed at eliminating ugly Liquid:
+
+:-1: Examples of **incorrect** code for this check:
+
+```liquid
+<!-- Around braces -->
+{% assign x = 1%}
+{{ x}}
+{{x }}
+
+<!-- After commas and semicolons -->
+{% form 'type',  object, key:value %}
+{% endform %}
+```
+
+:+1: Examples of **correct** code for this check:
+
+```liquid
+{% assign x = 1 %}
+{{ x }}
+{% form 'type', object, key: value, key2: value %}
+{% endform %}
+{{ "ignore:stuff,  indeed" }}
+{% render 'product-card',
+  product_card_product: product_recommendation,
+  show_vendor: section.settings.show_vendor,
+  media_size: section.settings.product_recommendations_image_ratio,
+  center_align_text: section.settings.center_align_text
+%}
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+SpaceInsideBraces:
+  enabled: true
+```
+
+## When Not To Use It
+
+If you don't care about the look of your code.
+
+## Version
+
+This check has been introduced in Theme Check 0.1.0.
+
+## Resources
+
+- [Liquid Style Guide][styleguide]
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[styleguide]: https://github.com/Shopify/liquid-style-guide
+[codesource]: /lib/theme_check/checks/space_inside_braces.rb
+[docsource]: /docs/checks/space_inside_braces.md

data/docs/checks/syntax_error.md

@@ -0,0 +1,49 @@
+# Prevent Syntax Errors (`SyntaxError`)
+
+This check exists to inform the user of Liquid syntax error earlier.
+
+## Check Details
+
+This check is aimed at eliminating syntax errors.
+
+:-1: Examples of **incorrect** code for this check:
+
+```liquid
+{% include 'muffin'
+{% assign foo = 1 }}
+{% unknown %}
+{% if collection | size > 0 %}
+```
+
+:+1: Examples of **correct** code for this check:
+
+```liquid
+{% include 'muffin' %}
+{% assign foo  = 1 %}
+{% if collection.size > 0 %}
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+SyntaxError:
+  enabled: true
+```
+
+## When Not To Use It
+
+It is not safe to disable this rule.
+
+## Version
+
+This check has been introduced in Theme Check 0.1.0.
+
+## Resources
+
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[codesource]: /lib/theme_check/checks/syntax_error.rb
+[docsource]: /docs/checks/syntax_error.md

data/docs/checks/template_length.md

@@ -0,0 +1,50 @@
+# Discourage the use of large template files (`TemplateLength`)
+
+This check exists to discourage the use of large template files. Use snippets to componentize your theme.
+
+## Check Details
+
+This check is aimed at eliminating large template files.
+
+:-1: Examples of **incorrect** code for this check:
+
+- Files that have more lines than the threshold
+
+:+1: Examples of **correct** code for this check:
+
+- Files that have less lines than the threshold
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+TemplateLength:
+  enabled: true
+  max_length: 200
+  exclude_schema: true
+```
+
+### `max_length`
+
+The `max_length` (Default: `200`) option determines the maximum number of lines allowed inside a liquid file.
+
+### `exclude_schema`
+
+The `exclude_schema` (Default: `true`) option determines if the schema lines from a template should be excluded from the line count.
+
+## When Not To Use It
+
+If you don't care about template lengths, then it's safe to disable this rule.
+
+## Version
+
+This check has been introduced in Theme Check 0.1.0.
+
+## Resources
+
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[codesource]: /lib/theme_check/checks/template_length.rb
+[docsource]: /docs/checks/template_length.md

data/docs/checks/translation_key_exists.md

@@ -0,0 +1,63 @@
+# Prevent use of undefined translations (`TranslationKeyExists`)
+
+This check exists to prevent translation errors in themes.
+
+## Check Details
+
+This check is aimed at eliminating the use of translations that do not exist.
+
+:-1: Examples of **incorrect** code for this check:
+
+```liquid
+{% comment %}locales/en.default.json{% endcomment %}
+{
+  "greetings": "Hello, world!",
+  "general": {
+    "close": "Close"
+  }
+}
+
+{% comment %}templates/index.liquid{% endcomment %}
+{{ "notfound" | t }}
+```
+
+:+1: Examples of **correct** code for this check:
+
+```liquid
+{% comment %}locales/en.default.json{% endcomment %}
+{
+  "greetings": "Hello, world!",
+  "general": {
+    "close": "Close"
+  }
+}
+
+{% comment %}templates/index.liquid{% endcomment %}
+{{ "greetings" | t }}
+{{ "general.close" | t }}
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+TranslationKeyExists:
+  enabled: true
+```
+
+## When Not To Use It
+
+It is not safe to disable this check.
+
+## Version
+
+This check has been introduced in Theme Check 0.1.0.
+
+## Resources
+
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[codesource]: /lib/theme_check/checks/translation_key_exists.rb
+[docsource]: /docs/checks/translation_key_exists.md

data/docs/checks/undefined_object.md

@@ -0,0 +1,53 @@
+# Prevent undefined object errors (`UndefinedObject`)
+
+This check prevents errors by making sure that no undefined variables are being used
+
+## Check Details
+
+This check is aimed at eliminating undefined object errors.
+
+:-1: Examples of **incorrect** code for this check:
+
+```liquid
+{% assign greetings = "Hello" %}
+{% if greeting == "Hello" %}
+
+{{ articl }}
+{{ prodcut }}
+```
+
+:+1: Examples of **correct** code for this check:
+
+```liquid
+{% assign greetings = "Hello" %}
+{% if greetings == "Hello" %}
+
+{{ article }}
+{{ product }}
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+UndefinedObject:
+  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
+
+- [Shopify Object Reference](https://shopify.dev/docs/themes/liquid/reference/objects)
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[codesource]: /lib/theme_check/checks/undefined_object.rb
+[docsource]: /docs/checks/undefined_object.md

data/docs/checks/unknown_filter.md

@@ -0,0 +1,45 @@
+# Prevent use of unknown filters (`UnknownFilter`)
+
+This check exists to prevent user errors.
+
+## Check Details
+
+This check is aimed at preventing the use of unknown filters.
+
+:-1: Examples of **incorrect** code for this check:
+
+```liquid
+{{ x | some_unknown_filter }}
+```
+
+:+1: Examples of **correct** code for this check:
+
+```liquid
+{{ x | upcase }}
+```
+
+## Check Options
+
+The default configuration for this check is the following:
+
+```yaml
+UnknownFilter:
+  enabled: true
+```
+
+## When Not To Use It
+
+It is not safe to disable this rule.
+
+## Version
+
+This check has been introduced in Theme Check 0.1.0.
+
+## Resources
+
+- [Shopify Filter Reference](https://shopify.dev/docs/themes/liquid/reference/filters)
+- [Rule Source][codesource]
+- [Documentation Source][docsource]
+
+[codesource]: /lib/theme_check/checks/unknown_filter.rb
+[docsource]: /docs/checks/unknown_filter.md