| 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:
- Web-search
site:shopify.dev theme performance for theme optimization
- Web-search
site:shopify.dev hydrogen caching for Hydrogen caching strategies
- Web-search
site:web.dev core web vitals for current CWV guidelines and thresholds
- Web-search
site:shopify.dev image optimization cdn for image URL transforms
- 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
const data = await storefront.query(QUERY, {
cache: CacheLong(),
});
const cart = await storefront.query(CART_QUERY, {
cache: CacheShort(),
});
| 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.
