eCommerce December 10, 2025

Shopify Theme Development Validation Techniques

shopify logo representing code errors

Shopify Code Validation & Testing Guide

Before Deploying ANY Code – Run These Checks

Method 1: Shopify Theme Check CLI (BEST)

Install

npm install -g @shopify/theme-check

Run

theme-check /path/to/your/theme

What It Catches

  • Invalid Liquid syntax
  • Missing required schema fields
  • Deprecated filters
  • Performance issues
  • Accessibility violations
  • Security issues

Fix Errors

  • Shows line numbers and exact problems
  • Follow recommendations in output
  • Re-run until 0 errors

Method 2: Shopify Online Store Editor (Built-in)

Location

Online Store → Themes → Actions → Edit code

How to Use

  1. Open any .liquid file
  2. Errors show inline with red underlines
  3. Click error for details
  4. Shows in real-time as you type

What It Catches

  • Liquid syntax errors
  • Unbalanced tags ({% without %})
  • Invalid schema JSON
  • Missing required attributes

Limitations

  • Doesn’t catch all issues
  • Less comprehensive than CLI
  • Only shows errors in open files

Method 3: Theme Inspector Chrome Extension

Install

Chrome Web Store → Search “Shopify Theme Inspector”

How to Use

  1. Install extension
  2. Open your store in Chrome
  3. Click extension icon
  4. View performance metrics, Liquid renders, errors

What It Shows

  • Liquid render times
  • Section load times
  • JavaScript errors
  • Asset loading issues
  • Performance bottlenecks

Method 4: Liquid Linter VS Code Extension

Install

VS Code Extensions → Search “Shopify Liquid”

Setup

  1. Install “Shopify Liquid” extension
  2. Open theme folder in VS Code
  3. Errors show inline

What It Catches

  • Liquid syntax
  • Tag balance
  • Filter usage
  • Variable scope issues

Method 5: Shopify Preview Before Publishing

Process

  1. Upload code to theme
  2. DO NOT publish
  3. Click “Preview” button
  4. Test thoroughly in preview mode
  5. Check browser console (F12) for errors

What to Test

  • All page types (product, collection, home, etc.)
  • Mobile responsiveness
  • Forms submit correctly
  • Navigation works
  • Images load
  • Payment icons appear
  • Newsletter signup functions

Check Browser Console

Press F12 → Console tab Look for:

  • Red errors (JavaScript failures)
  • 404s (missing assets)
  • CORS errors
  • API failures

Method 6: Manual Code Review Checklist

Liquid Syntax

  • [ ] All {% have matching %}
  • [ ] All {{ have matching }}
  • [ ] All {% if %} have {% endif %}
  • [ ] All {% for %} have {% endfor %}
  • [ ] No nested {% comment %} blocks

Schema Validation

  • [ ] Valid JSON (no trailing commas)
  • [ ] All type values are valid Shopify types
  • [ ] url type fields have NO default values
  • [ ] All required fields present (name, settings)
  • [ ] Setting IDs use underscores, not hyphens

Shopify Standards

  • [ ] Use {{ 'asset.css' | asset_url }} not hardcoded paths
  • [ ] Use {{ product.price | money }} not manual formatting
  • [ ] Use {{ 'now' | date: "%Y" }} for current year
  • [ ] Use {{ shop.name }} not hardcoded store name
  • [ ] Use {% form 'customer' %} for newsletter, not HTML forms

ADA Compliance

  • [ ] All text minimum 14px (16px body text)
  • [ ] All interactive elements minimum 16px
  • [ ] Contrast ratio 4.5:1 minimum
  • [ ] All colors pure black (#000000) on light backgrounds
  • [ ] All images have alt attributes
  • [ ] All buttons have aria-label if icon-only
  • [ ] Semantic HTML (<footer>, <nav>, <header>)

Performance

  • [ ] CSS in external file or <style> tag, not inline
  • [ ] JavaScript at bottom or deferred
  • [ ] Images use loading="lazy"
  • [ ] SVGs inline for icons (not image files)
  • [ ] No unnecessary third-party scripts

Validation Workflow (Use This Order)

  1. Write code
  2. Run Theme Check CLI → Fix all errors
  3. Check VS Code Linter → Fix warnings
  4. Upload to Shopify (unpublished theme)
  5. Check Online Editor → Fix any new errors
  6. Preview in browser → Test functionality
  7. Check Console (F12) → Fix JavaScript errors
  8. Test mobile → Check responsive design
  9. Run accessibility checker → Fix ADA issues
  10. THEN publish

Common Errors & Fixes

“Invalid schema: setting with id=’X’ default must be a string”

Fix: Remove default from url type settings

// WRONG
{"type": "url", "id": "link", "default": "https://example.com"}

// RIGHT
{"type": "url", "id": "link"}

“Unbalanced tag”

Fix: Count opening/closing tags

{% if condition %}     <!-- +1 -->
  {% if nested %}      <!-- +1 -->
  {% endif %}          <!-- -1 -->
{% endif %}            <!-- -1 -->
Total should equal 0

“Unknown filter: stylesheet_tag”

Fix: Use modern syntax

<!-- WRONG -->
{{ 'style.css' | asset_url | stylesheet_tag }}

<!-- RIGHT -->
<link rel="stylesheet" href="{{ 'style.css' | asset_url }}">

“Menu ‘footer-shop’ not found”

Fix: Create menu in Navigation with exact handle

  • Go to Navigation
  • Create menu
  • Handle must match code exactly (case-sensitive)

“Payment icons not showing”

Fix: Enable payment methods

  • Settings → Payments
  • Enable at least one payment provider
  • Icons auto-populate from enabled methods

Testing Checklist Before Going Live

Functionality

  • [ ] All links work (no 404s)
  • [ ] Forms submit successfully
  • [ ] Search works
  • [ ] Cart add/remove works
  • [ ] Checkout loads
  • [ ] Payment methods display

Content

  • [ ] All images load
  • [ ] Text is readable
  • [ ] No Lorem ipsum placeholder text
  • [ ] Contact info correct
  • [ ] Store hours accurate
  • [ ] Legal pages exist (Privacy, Terms)

Performance

  • [ ] Page loads under 3 seconds
  • [ ] No console errors (F12)
  • [ ] Images optimized
  • [ ] No broken assets

Mobile

  • [ ] Responsive on phone
  • [ ] Touch targets 44x44px minimum
  • [ ] Hamburger menu works
  • [ ] Phone number clickable
  • [ ] Forms usable on mobile

Accessibility

  • [ ] Keyboard navigation works (Tab through page)
  • [ ] Screen reader compatible
  • [ ] Color contrast passes
  • [ ] Text is readable without zoom
  • [ ] All form inputs labeled

SEO

  • [ ] Meta titles set
  • [ ] Meta descriptions set
  • [ ] H1 tags present on pages
  • [ ] Alt text on images
  • [ ] Sitemap accessible

Tools Summary

Tool Best For Installation
Theme Check CLI Comprehensive validation npm install -g @shopify/theme-check
Online Editor Quick syntax checks Built into Shopify
Theme Inspector Performance debugging Chrome extension
VS Code Liquid Development workflow VS Code extension
Browser Console Runtime errors F12 in browser

When You See Errors

  1. Read the error message – tells you what’s wrong
  2. Note the line number – tells you where
  3. Check this guide – common fixes documented
  4. Google the exact error – Shopify docs have answers
  5. Test the fix – re-validate after changes
  6. Document the solution – for next time

Quick Reference Commands

# Install theme check
npm install -g @shopify/theme-check

# Run validation
theme-check /path/to/theme

# Run on specific file
theme-check sections/footer.liquid

# Auto-fix (use with caution)
theme-check --auto-correct

# Check specific category
theme-check --only LiquidTag

Resources

  • Shopify Theme Check: https://github.com/Shopify/theme-check
  • Liquid Docs: https://shopify.dev/docs/api/liquid
  • Theme Best Practices: https://shopify.dev/docs/themes/best-practices
  • Section Schema: https://shopify.dev/docs/themes/architecture/sections/section-schema
  • WCAG Guidelines: https://www.w3.org/WAI/WCAG21/quickref/

Save this doc. Reference it before every deployment.

Last Updated: December 2025