---

name: shopify-performance description: Optimize Shopify performance — Liquid rendering, asset optimization, CDN strategies, Core Web Vitals, Hydrogen caching, image optimization, preloading, and lazy loading. Use when improving Shopify store speed. allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch

Shopify Performance Optimization

Before writing code

Fetch live docs:

1. Web-search site:shopify.dev theme performance for theme optimization
2. Web-search site:shopify.dev hydrogen caching for Hydrogen caching strategies
3. Web-search site:web.dev core web vitals for current CWV guidelines and thresholds
4. Web-search site:shopify.dev image optimization cdn for image URL transforms
5. Web-search site:shopify.dev theme speed report for Shopify's built-in speed metrics

Liquid Rendering Performance

Template Optimization

• Minimize Liquid logic — complex loops and conditionals slow server-side rendering
• Use {% render %} (not {% include %}) — isolated scope prevents variable conflicts
• Avoid nested loops — O(n²) in Liquid is expensive
• Limit forloop iterations with limit: parameter
• Pre-compute values with {% assign %} instead of repeating expressions

Object Access

• Access specific properties: {{ product.title }} not {{ product | json }}
• Avoid all_products[handle] in loops — each is a separate data lookup
• Use section settings to pass data instead of global lookups
• Minimize use of {{ content_for_header }} scripts (managed by Shopify — cannot remove, but minimize additional scripts)

Liquid Anti-Patterns

| Anti-Pattern | Why It's Slow | Better Approach | |-------------|--------------|-----------------| | Nested for loops | O(n²) rendering | Flatten data, use single loop | | all_products[handle] in loop | Data fetch per iteration | Pass products via section settings | | {% include %} with variables | Shared scope causes conflicts | Use {% render %} (isolated) | | Complex {% if %} chains | Evaluated every render | Simplify conditions, use {% case %} | | Unused sections in templates | Rendered even if hidden | Remove from JSON template |

Asset Optimization

CSS

• Minimize CSS — remove unused styles
• Use {{ 'style.css' | asset_url | stylesheet_tag }} for proper caching
• Critical CSS: inline above-the-fold styles in <head>
• Defer non-critical CSS: media="print" onload="this.media='all'"

JavaScript

• Defer non-critical JS: <script defer> or dynamic import()
• Minimize JS bundles — Shopify themes don't need frameworks for most UI
• Use native browser APIs over jQuery
• Load third-party scripts asynchronously (async attribute)
• Avoid render-blocking scripts in <head>

Images

Shopify CDN image optimization:

# Responsive images with srcset
{{ image | image_url: width: 800 }}
{{ image | image_url: width: 400 }}

# Srcset pattern
<img
  srcset="{{ image | image_url: width: 400 }} 400w,
         {{ image | image_url: width: 800 }} 800w,
         {{ image | image_url: width: 1200 }} 1200w"
  sizes="(max-width: 600px) 400px, (max-width: 1000px) 800px, 1200px"
  src="{{ image | image_url: width: 800 }}"
  alt="{{ image.alt }}"
  loading="lazy"
  width="{{ image.width }}"
  height="{{ image.height }}"
>

Key image practices:

• Use loading="lazy" for below-the-fold images
• Use fetchpriority="high" for LCP image
• Set explicit width and height to prevent layout shift
• Shopify CDN automatically serves WebP/AVIF when supported
• URL parameters: ?width=, ?height=, ?crop=, ?format=

Fetch live docs: Web-search site:shopify.dev image_url filter parameters for current CDN transform options — new parameters are added over time.

Core Web Vitals

LCP (Largest Contentful Paint)

Target: < 2.5 seconds

• Preload hero/LCP image: <link rel="preload" as="image" href="{{ image | image_url: width: 1200 }}">
• Use fetchpriority="high" on LCP image
• Avoid lazy-loading above-the-fold images
• Minimize render-blocking CSS and JS
• Use server-side rendering (Liquid or Hydrogen SSR)

CLS (Cumulative Layout Shift)

Target: < 0.1

• Set explicit width and height on all images and media
• Reserve space for dynamic content (ads, embeds, lazy-loaded images)
• Avoid inserting content above existing content after page load
• Use aspect-ratio CSS property for responsive media containers
• Avoid dynamically injected banners or pop-ups that shift content

INP (Interaction to Next Paint)

Target: < 200ms

• Minimize main-thread blocking JavaScript
• Break up long tasks with requestIdleCallback or setTimeout(fn, 0)
• Use CSS for animations and transitions (not JS)
• Debounce event handlers (scroll, resize, input)
• Avoid synchronous layout thrashing (read-then-write DOM patterns)

Fetch live docs: CWV thresholds and measurement methodology evolve. Web-search site:web.dev core web vitals thresholds for current targets.

Hydrogen Caching

Cache Strategies

// Pattern: apply cache strategy to storefront query
const data = await storefront.query(QUERY, {
  cache: CacheLong(),  // products, collections
});

const cart = await storefront.query(CART_QUERY, {
  cache: CacheShort(), // dynamic data
});

| Strategy | Use For | |----------|---------| | CacheLong() | Products, collections, pages | | CacheShort() | Cart, personalized content | | CacheNone() | Customer-specific data | | CacheCustom({...}) | Fine-tuned scenarios |

Fetch live docs for exact TTL values — Hydrogen caching defaults may change across versions.

Streaming SSR

• Use defer() in loaders for non-critical data
• Critical data renders immediately, deferred data streams in
• Show loading states with <Suspense> + <Await>
• Preload routes with <Link prefetch="intent">

Shopify CDN

Shopify's global CDN:

• Automatic for all theme assets and images
• Cache-Control headers managed by Shopify
• Image transformations via URL parameters
• No manual CDN configuration needed for themes
• Asset fingerprinting for cache busting

Measurement Tools

| Tool | What It Measures | |------|-----------------| | Shopify Theme Speed Report | Overall theme score in admin | | Google Lighthouse | CWV + performance audit | | WebPageTest | Real-world loading waterfall | | Chrome DevTools Performance | JS profiling, layout shifts | | Search Console CWV Report | Field data from real users |

Best Practices

• Measure before optimizing — use Lighthouse, WebPageTest, Shopify's theme speed report
• Focus on LCP image optimization first (biggest impact for most stores)
• Lazy-load everything below the fold
• Minimize third-party scripts (analytics, chat widgets, social embeds)
• Use Shopify's built-in analytics over custom tracking scripts where possible
• For Hydrogen: cache aggressively, stream non-critical data, preload routes
• Test on real devices and slow connections (3G throttling)
• Set explicit dimensions on all media to prevent CLS
• Use font-display: swap for custom fonts

Fetch the Shopify performance documentation, Core Web Vitals guides, and Hydrogen caching docs for exact optimization techniques and current best practices before implementing.