theme-check-theory

Theory Digital's custom Shopify Theme Check rules — house standards enforced on top of theme-check:recommended.

Built for the TypeScript Theme Check engine (@shopify/theme-check-common v3) integrated into Shopify CLI. It is not compatible with the archived Ruby Shopify/theme-check project.

Checks

| Code | Severity | What it catches | | --- | --- | --- | | UnusedSectionSettings | warning | A setting declared in {% schema %} that is never referenced in the file. | | UnguardedTextSetting | warning | A text-like setting output with {{ }} and no presence guard ({% if %}/{% unless %}) or \| default. |

UnusedSectionSettings

This single-file check collects every id under settings and blocks[].settings in the schema, then collects static section.settings.<id> and block.settings.<id> references in the Liquid. It reports every declared setting that has no matching reference.

If a file uses dynamic access such as section.settings[key], or passes an entire settings object elsewhere, the check cannot prove which setting is unused. It therefore stays silent for the whole file to avoid false positives.

UnguardedTextSetting

Text-like settings render as an empty string when a merchant leaves them blank, so outputting them unguarded is a recurring bug source. A setting is considered handled if, anywhere in the file, it is either tested in an if, unless, elsif, or case conditional, or output with a default filter.

Version 1 is deliberately coarse and per-file. It favors near-zero false positives over catching a setting guarded in one branch and output raw in another.

The setting types considered text-like are configurable with textualSettingTypes. The defaults are text, textarea, richtext, inline_richtext, html, liquid, and url.

UnguardedTextSetting:
  enabled: true
  severity: warning
  textualSettingTypes:
    - text
    - textarea
    - image_picker

Usage in a project

Install the module as a development dependency:

npm install --save-dev theme-check-theory

Reference its CommonJS entry point from the project's .theme-check.yml:

extends:
  - theme-check:recommended

require:
  - ./node_modules/theme-check-theory

UnusedSectionSettings:
  enabled: true
  severity: warning

UnguardedTextSetting:
  enabled: true
  severity: warning

See .theme-check.example.yml for a copyable configuration. The custom-check-only settings are also available in configs/recommended.yml.

Run Theme Check through Shopify CLI:

shopify theme check

CI

Start new checks at warning or info so they surface without blocking. Review the findings across existing themes, then promote them to error once the themes are clean.

# .github/workflows/theme-check.yml
- run: npm ci
- run: npx shopify theme check --fail-level error

Development

npm install
npm test
npm run build

Tests use runLiquidCheck and check from @shopify/theme-check-common/dist/test/test-helper, so Vitest exercises the real Theme Check parser and traversal rather than a mocked AST.

Adding a check

1. Create src/checks/<name>.ts exporting a LiquidCheckDefinition.
2. Add it to the checks array in src/index.ts.
3. Add src/checks/<name>.test.ts with true-positive and false-positive cases.
4. Add it to configs/recommended.yml.

Shared schema parsing and setting-reference helpers live in src/utils/ast.ts. Their node shapes are verified against @shopify/liquid-html-parser 2.9.x; run the tests when upgrading that dependency.