Theme Check linting tool

Theme Check is Shopify's official linter for Liquid themes. It analyzes theme code and catches issues that affect all Core Web Vitals: parser-blocking scripts without defer or async, remote assets on external domains, missing preconnect hints for the Shopify CDN, img tags without width and height attributes, and oversized pagination. Opt-in checks add asset size limits for CSS and JavaScript. It also catches code quality problems and best practice violations.

Anchor to InstallationInstallation

Theme Check is built into Shopify CLI:

Anchor to Running Theme CheckRunning Theme Check

Anchor to Via command lineVia command line

Anchor to Via code editorVia code editor

Theme Check integrates with VS Code through the Liquid language server extension.

Anchor to In CI/CD pipelineIn CI/CD pipeline

Anchor to Common checks explainedCommon checks explained

• AssetSizeCSS and AssetSizeJavaScript: Flags asset files that exceed a size threshold. The defaults are 100000 bytes for CSS and 10000 bytes for JavaScript. Both checks measure the raw file size on disk, or the Content-Length of a remote asset. They don't measure minified or compressed size, even though the reported message mentions compression. Fix by breaking into smaller files, removing unused code, or using async loading.
• ParserBlockingScript: Identifies scripts that block HTML parsing. Use the defer or async attribute.
• RemoteAsset: Warns about external domains. Self-host on the Shopify CDN using the asset_url filter.
• CdnPreconnect: Flags redundant preconnect hints to the Shopify CDN, which the platform already sends.
• ImgWidthAndHeight: Flags img tags that are missing width and height attributes, which causes layout shift.
• PaginationSize: Makes sure that pagination sizes stay within a performant range. The default is maxSize: 250.
• AssetPreload: Encourages Liquid filters over HTML for preloads. Use stylesheet_tag: preload: true instead of HTML preload tags to trigger Early Hints.

Anchor to ConfigurationConfiguration

Create .theme-check.yml to enable the asset size checks and customize thresholds. Setting names are camelCase. An unrecognized name, such as the snake_case threshold_in_bytes, logs an Unexpected setting warning and is ignored:

Anchor to Disable checks selectivelyDisable checks selectively

Use Liquid comments to disable specific checks when necessary, and document why:

Anchor to WorkflowWorkflow

Use Theme Check as the first line of defense, then layer in browser-based tools for deeper analysis:

1. During development: Run Theme Check frequently.
2. Before commit: Clean up all errors with shopify theme check --auto-correct.
3. In CI/CD: Block merges with errors.
4. With other tools: Combine with browser testing, such as Lighthouse, WebPageTest, and Theme Inspector.

All tools complement each other. Use Theme Check first.

Some checks support auto-fix:

Auto-fixes: deprecated filter replacements, missing template files, required layout objects, and some syntax issues.

Manual fixes are required for performance issues, architectural problems, and business logic decisions.

Anchor to ReferencesReferences

• asset_url filter
• stylesheet_tag filter
• preload_tag filter
• Theme Check configuration
• Theme Check checks reference
• Shopify CLI theme commands
• Finding your worst JavaScript offenders
• Audit and remove third-party scripts