--- title: Theme Check linting tool description: >- Use Shopify's official linter to catch performance violations and code quality problems, including oversized bundles, parser-blocking scripts, and remote assets, before deployment. source_url: html: >- https://shopify.dev/docs/storefronts/themes/best-practices/performance/theme-check-tool md: >- https://shopify.dev/docs/storefronts/themes/best-practices/performance/theme-check-tool.md api_name: liquid --- # Theme Check linting tool [Theme Check](https://shopify.dev/docs/storefronts/themes/tools/theme-check) is Shopify's official linter for Liquid themes. It analyzes theme code and catches issues that affect all [Core Web Vitals](https://web.dev/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. *** ## Installation Theme Check is built into Shopify CLI: ```bash npm install -g @shopify/cli shopify version ``` *** ## Running Theme Check ### Via command line ```bash shopify theme check shopify theme check --path sections/ shopify theme check --auto-correct ``` ### Via code editor Theme Check integrates with VS Code through the Liquid language server extension. ### In CI/CD pipeline ```yaml - run: shopify theme check ``` *** ## Common checks explained * [`AssetSizeCSS`](https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/asset-size-css) and [`AssetSizeJavaScript`](https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/asset-size-javascript): 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`](https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/parser-blocking-javascript): Identifies scripts that block HTML parsing. Use the `defer` or `async` attribute. * [`RemoteAsset`](https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/remote-asset): Warns about external domains. Self-host on the Shopify CDN using the `asset_url` filter. * [`CdnPreconnect`](https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/cdn-preconnect): Flags redundant preconnect hints to the Shopify CDN, which the platform already sends. * [`ImgWidthAndHeight`](https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/img-width-and-height): Flags `img` tags that are missing `width` and `height` attributes, which causes layout shift. * [`PaginationSize`](https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/pagination-size): Makes sure that pagination sizes stay within a performant range. The default is `maxSize: 250`. * [`AssetPreload`](https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks/asset-preload): Encourages Liquid filters over HTML for preloads. Use `stylesheet_tag: preload: true` instead of HTML preload tags to trigger Early Hints. **Note:** `AssetSizeCSS` and `AssetSizeJavaScript` aren't part of the recommended configuration, so they don't run unless you enable them. They're omitted from the recommended config rather than switched off with `enabled: false`, so adding them to your `.theme-check.yml` is what turns them on. *** ## Configuration 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: ```yaml AssetSizeCSS: enabled: true thresholdInBytes: 100000 AssetSizeJavaScript: enabled: true thresholdInBytes: 10000 PaginationSize: enabled: true maxSize: 250 ``` *** ## Disable checks selectively Use Liquid comments to disable specific checks when necessary, and document why: ```liquid {% # theme-check-disable AssetSizeJavaScript %} {% # theme-check-enable AssetSizeJavaScript %} ``` *** ## Workflow 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. | Tool | Purpose | When to use | | - | - | - | | Theme Check | Static code analysis, catches errors before runtime | During development, every commit | | Theme Inspector | Profile actual Liquid rendering performance | When TTFB is slow | | Lighthouse | Overall performance metrics in lab | Before launch, periodic audits | | WebPageTest | Real-world performance, network waterfalls | Detailed debugging | All tools complement each other. Use Theme Check first. Some checks support auto-fix: ```bash shopify theme check --auto-correct ``` 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. *** ## References * [`asset_url`](https://shopify.dev/docs/api/liquid/filters/asset_url) filter * [`stylesheet_tag`](https://shopify.dev/docs/api/liquid/filters/stylesheet_tag) filter * [`preload_tag`](https://shopify.dev/docs/api/liquid/filters/preload_tag) filter * [Theme Check configuration](https://shopify.dev/docs/storefronts/themes/tools/theme-check/configuration) * [Theme Check checks reference](https://shopify.dev/docs/storefronts/themes/tools/theme-check/checks) * [Shopify CLI theme commands](https://shopify.dev/docs/api/shopify-cli/theme/theme-check) * [Finding your worst JavaScript offenders](https://shopify.dev/docs/storefronts/themes/best-practices/performance/finding-worst-offenders) * [Audit and remove third-party scripts](https://shopify.dev/docs/storefronts/themes/best-practices/performance/audit-remove-third-party-scripts) ***