Shopify Theme Check is a tool that helps you ensure your theme’s code meets Shopify’s standards and best practices. It checks for issues in your Liquid templates, JSON configurations, and JavaScript files, improving performance, SEO, and usability. Here’s what you need to know to get started:
Key Benefits:
- Faster Load Times: Reduces delays by optimizing code.
- Improved SEO: Ensures search engine-friendly structures.
- Better User Experience: Fixes accessibility and mobile usability issues.
- Code Quality: Enforces clean, reusable, and secure coding practices.
Quick Setup Steps:
- Install Requirements: Use Node.js (v14+), npm (v7+), or Homebrew (for macOS).
- Install Theme Check:
- With npm:
npm install -g @shopify/cli @shopify/theme - With Homebrew:
brew install shopify-cli
- With npm:
- Verify Installation: Run
shopify theme check --version. - Configure Checks: Customize
.theme-check.ymlfor your project. - Run Checks: Use
shopify theme check ./theme-dirto scan your theme.
Key Features:
- Liquid Analysis: Detects logic errors.
- JSON Schema Checks: Validates configurations.
- Performance Optimization: Enforces fast-loading assets.
- Accessibility & SEO: Improves usability and visibility.
Integration Tips:
- Add pre-commit hooks to prevent committing errors.
- Use the Shopify Liquid extension in VS Code for real-time error detection.
- Automate checks in CI/CD pipelines with GitHub Actions.
Whether you’re a developer or store owner, Shopify Theme Check ensures your theme is optimized, error-free, and ready for success.
Getting started with the Shopify CLI (theme development)
How to Install Theme Check
Now that we’ve covered why Theme Check is useful, let’s look at how to install it. Below are the steps and requirements you need to know.
System Requirements
Before diving into installation, make sure your setup meets these basic requirements:
| Component | Minimum Version | Notes |
|---|---|---|
| Node.js | v14 or higher | Needed for npm installation |
| npm | v7 or higher | Acts as the package manager |
| Operating System | Windows/macOS/Linux | Compatible across platforms |
- macOS users: Install Xcode command line tools first.
- Linux users: Make sure to install the
libsecret-devpackage.
Installation Methods: npm and Homebrew
You can install Theme Check using either npm (works on all platforms) or Homebrew (for macOS users). Follow the steps below:
Using npm (All Platforms)
To install Theme Check globally, run:
npm install -g @shopify/cli @shopify/theme
This will make Theme Check available system-wide.
Using Homebrew (macOS)
If you’re on macOS, you can use Homebrew for a straightforward installation process:
brew tap shopify/shopify
brew install shopify-cli
Verifying Installation
After installation, confirm everything is working by running:
shopify theme check --version
shopify theme check ./theme-dir
"Run
shopify theme check --initto generate configuration files for immediate productivity." – E-commerce Dev Group [1][5]
With these steps, you’ll be ready to start using Theme Check in your development workflow.
Basic Setup and Configuration
Once you’ve installed Theme Check, you’ll need to configure it to suit your project’s structure and needs.
Setting Up the Config File
The .theme-check.yml file, located in your theme’s root directory, comes preloaded with Shopify’s recommended settings. By default, it extends theme-check:recommended, covering checks for Liquid, Performance, and Translation categories.
If your project uses a non-standard directory structure, update the root path in the configuration file:
root: dist/
ignore: # Standard build artifacts and IDE files
Adjusting Check Settings
You can customize the checks with the following options:
| Setting Type | Purpose | Example Configuration |
|---|---|---|
| Severity Levels | Set the importance of checks | severity: error/warning/info |
| Check Status | Enable or disable specific checks | enabled: true/false |
| Extended Configs | Add extra rules | extends: [theme-check:recommended] |
| Custom Rules | Define project-specific checks | require: ./custom-checks.rb |
For team-based projects, you can merge Shopify’s recommended checks with your custom rules by extending multiple configurations:
extends:
- theme-check:recommended
- ./team-rules.yml
require:
- ./node_modules/shopify-extras
This approach ensures you can combine Shopify’s standard checks with any additional rules tailored to your workflow.
To confirm your configuration, list all active checks and their severity levels by running:
shopify theme check --list
This command provides a clear overview of your enabled checks, helping you fine-tune your setup for development.
Running Theme Check
With your .theme-check.yml file set up, you can run scans using these key commands and options:
Standard Check Commands
Theme Check allows you to analyze your theme efficiently through straightforward command-line commands.
Command Options and Settings
You can customize your checks using several command-line options:
| Option Flag | Purpose | Example Usage |
|---|---|---|
--config (-C) |
Use a custom config file | shopify theme check -C prod-config.yml |
--auto-correct (-a) |
Automatically fix issues | shopify theme check -a ./theme |
--fail-level |
Set the failure threshold | shopify theme check --fail-level warning |
--output (-o) |
Generate formatted reports | shopify theme check -o json > report.json |
The --auto-correct flag is especially handy. It can automatically fix up to 43% of common problems, like missing ALT tags or basic Liquid syntax issues [1].
Reading Check Results
Scan results group issues by severity:
- Errors: Serious problems that block deployment.
- Warnings: Issues to review before deployment.
- Info: Suggestions for improving optimization.
For instance:
templates/product.liquid:1 Warning - 'product' is undefined [LiquidVariableNotFound]
If you’re working in a CI/CD pipeline, the JSON output format is ideal for seamless integration:
shopify theme check --output json > theme-check-results.json
The JSON format organizes results by file paths, error codes, severity levels, and messages, making it easy for machines to process.
Exit codes help you understand the scan results: 0 means success, while 1 indicates issues at or above the specified fail-level.
Adding Theme Check to Development Tools
Incorporating Theme Check into your development process helps ensure code quality at every stage.
Setting Up IDE Tools
Enable real-time feedback in your code editor for seamless error detection:
If you’re using Visual Studio Code, the Shopify Liquid extension provides real-time validation. Update your settings.json file with the following configuration:
{
"shopifyLiquid.shopifyCLIPath": "/usr/local/bin/shopify",
"themeCheck.checkOnSave": true,
"themeCheck.checkOnOpen": true
}
This setup allows you to catch issues as you write code.
Adding Pre-Commit Checks
Prevent committing code with errors by setting up a pre-commit hook using Husky. Add this configuration to your package.json:
"husky": {
"hooks": {
"pre-commit": "shopify theme check --fail-level=error"
}
}
This ensures that only error-free code is committed to your repository.
Setting Up Pipeline Checks
For CI/CD workflows, integrate Theme Check to catch issues before deployment. Use the following GitHub Actions workflow file (.github/workflows/theme-check.yml):
name: Theme Check
on: [push, pull_request]
jobs:
theme-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Install Shopify CLI
run: npm install -g @shopify/cli @shopify/theme
- name: Run Theme Check
run: shopify theme check --config .theme-check.yml --fail-level=error
This setup helps ensure that errors impacting performance are caught early.
"Implementing automated Theme Check in CI pipelines has reduced deployment issues by 43% for our clients’ stores", says E-commerce Dev Group [1][5].
Fixing Common Problems
Theme Check can sometimes produce incorrect warnings or run into configuration issues, disrupting your development workflow. Below, we’ll explore practical ways to address these challenges.
Handling Incorrect Warnings
Occasionally, Theme Check may flag valid code as problematic. To bypass these false positives while keeping your code clean, you can use suppression comments for specific cases:
{% # theme-check-disable LiquidTag %}
{{ product.title | custom_filter }}
{% # theme-check-enable LiquidTag %}
If the same false positive keeps appearing, you can configure Theme Check to ignore specific files:
LiquidTag:
enabled: true
ignore_files:
- snippets/custom-feature.liquid
Fixing Config Issues
Configuration issues often result from incorrect file paths or invalid check definitions. These can lead to checks not running or behaving unexpectedly. Here’s how to troubleshoot:
| Problem | Suggested Fix |
|---|---|
| Invalid check names | Cross-check with the official documentation |
| File path errors | Ensure the correct root directory is set |
| Duplicate definitions | Prioritize and clean up extended configs |
For custom directory setups, make sure your paths are mapped correctly:
root: dist/
ignore:
- dist/templates/customers/*
- node_modules/**/*
Version Compatibility Issues
Version mismatches between Theme Check and the Shopify API can lead to unexpected issues. To avoid this, always specify the exact Theme Check version in your package.json:
"devDependencies": {
"@shopify/theme-check": "1.8.2"
}
If you encounter deprecated checks, replace them with newer alternatives. For example:
# Replace outdated ImgLazyLoading with ImgLoadingAttribute
ImgLazyLoading:
enabled: false
ImgLoadingAttribute:
enabled: true
Getting Expert Theme Help
While Theme Check can automatically address many issues, some problems are best handled by professionals.
When to Call in the Experts
Certain warnings from Theme Check point to more complex technical problems that need expert attention. Here are some common warning patterns and their solutions:
| Warning Pattern | Suggested Solution |
|---|---|
| 50+ unresolved warnings | Schema updates and optimizing templates |
| Lighthouse scores below 80 | Optimizing assets to reduce size by 40-60% |
| "Asset not found" errors | Developing custom extensions with validated assets |
| Recurring Liquid syntax issues | Refactoring code and fixing responsive design problems |
Other situations where expert help is essential include:
- Performance Challenges: When render-blocking resources identified by Theme Check disrupt the layout and user experience [3].
- Integration Issues: When conflicts arise with subscription services or other vital apps [6].
- Template Glitches: Persistent infinite loops in product recommendations that resist previous fixes [5].
If these problems continue despite attempts to fix them, it’s time to seek specialized support.
E-commerce Dev Group’s Expertise
E-commerce Dev Group offers tailored solutions for resolving advanced Theme Check issues. Their services include:
- Custom Validation Checks: Creating store-specific patterns to validate theme structures [4].
- Advanced Multi-Store Configurations: Setting up themes that work seamlessly across multiple stores [1].
Their approach combines manual code reviews with custom ignore rules for critical components [5][2]. This ensures thorough resolution of key issues while keeping your theme adaptable to your needs.
Conclusion: Better Theme Development
Key Advantages
Using Theme Check as described earlier offers developers noticeable improvements in their workflow and code quality. Here’s what the tool brings to the table:
- Fewer Liquid Errors: A 68% reduction in Liquid errors has been observed [7].
- Improved Accessibility: It eliminates up to 92% of accessibility issues [5].
- Faster Loading Times: Stores show a 42% improvement in Largest Contentful Paint (LCP) scores [3].
- Time Savings: Teams save 8–12 hours per month on fixes.
- Speedier Code Reviews: Reviews are completed 35% faster.
How to Get Started
To keep enjoying these advantages over time, follow these steps:
- Use Real-Time Diagnostics: Install the VS Code extension to get instant feedback and quick-fix options as you code [2].
- Track Metrics: Focus on resolving errors within 24 hours and aim for fewer than 0.5 defects per file [4][7].
