shopify-performance
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.
Best use case
shopify-performance is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
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.
Teams using shopify-performance should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/shopify-performance/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How shopify-performance Compares
| Feature / Agent | shopify-performance | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
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.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# 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:
```liquid
# 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
```typescript
// 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.Related Skills
woo-performance
Optimize WooCommerce performance — object caching, transients, HPOS, database optimization, Action Scheduler, lazy loading, and query optimization. Use when improving store performance or diagnosing slowness.
spree-performance
Profile and optimize a Spree application — N+1 queries with bullet/scout, database indexing strategy for Spree's polymorphic associations, Rails fragment + Russian doll caching, ActiveStorage variant pre-generation, Sidekiq queue tuning, MeiliSearch vs Postgres FTS tradeoffs, Puma worker/thread sizing, CDN strategy for catalog pages, asset precompile time, and load testing. Use when Spree is slow, the database is hot, or you're preparing for a traffic spike (Black Friday, launch).
shopify-webhooks
Implement Shopify webhooks — subscription methods (HTTP, EventBridge, Pub/Sub, SQS), HMAC verification, mandatory GDPR webhooks, delivery methods, retry policy, and idempotency. Use when building event-driven Shopify integrations.
shopify-themes
Develop Shopify themes — file structure, Online Store 2.0, sections and blocks, settings schema, Dawn reference theme, Theme Check linting, asset pipeline, and theme deployment. Use when building or customizing Shopify themes.
shopify-testing
Test Shopify applications — app testing with Vitest and Playwright, theme testing with Theme Check, Function testing, webhook testing, extension testing, and CI/CD pipelines. Use when writing tests for Shopify projects.
shopify-setup
Set up a Shopify development environment — Shopify CLI installation, Partner account, development stores, environment variables, project structures for themes, apps, and Hydrogen. Use when starting a new Shopify project.
shopify-security
Secure Shopify applications — HMAC webhook verification, session token validation, OAuth scope management, Content Security Policy, GDPR mandatory webhooks, input validation, and secure coding practices. Use when implementing Shopify security features.
shopify-polaris
Build Shopify app UIs with Polaris — component categories, Web Components transition, React legacy components, App Design Guidelines, accessibility, @shopify/draggable, and design tokens. Use when building Shopify admin app interfaces.
shopify-liquid
Write Shopify Liquid templates — objects, tags, filters, global objects, section schema, Online Store 2.0 JSON templates, and Liquid best practices. Use when customizing Shopify theme templates.
shopify-hydrogen
Build headless Shopify storefronts with Hydrogen — Remix-based framework, Oxygen deployment, storefront.query(), caching strategies, cart, customer accounts, SEO, and analytics. Use when building custom Shopify storefronts.
shopify-functions
Build Shopify Functions — serverless WebAssembly extensions for discounts, delivery customization, payment customization, cart validation, cart transforms, and order routing. Use when extending Shopify's backend logic.
shopify-customers
Manage Shopify customers — Customer Account API, new vs classic accounts, Multipass SSO, customer segmentation, B2B company accounts, metafields, and marketing consent. Use when working with Shopify customer data.