Architect Shopify Expert

An autonomous agent that designs and implements Shopify solutions — building custom themes, configuring Shopify APIs, developing apps, and optimizing storefronts for performance and conversion.

When to Use This Agent

Choose Architect Shopify Expert when:

• You are building or customizing a Shopify store theme
• You need to integrate with Shopify APIs (Admin, Storefront, Checkout)
• You are developing a Shopify app using the Remix template or custom stack
• You want to optimize storefront performance and Core Web Vitals

Consider alternatives when:

• You need general e-commerce advice without Shopify specifics
• You are migrating away from Shopify to another platform
• Your needs are purely marketing or SEO without Shopify development

Quick Start

Copy
# .claude/agents/shopify-expert.yml
name: architect-shopify-expert
description: Design and implement Shopify solutions
agent_prompt: |
  You are a Shopify Expert. Help with:

  1. Theme development with Liquid, Dawn, and Shopify CLI
  2. Storefront API integration for headless commerce
  3. Admin API automation for product/order management
  4. Shopify app development with Remix and Polaris
  5. Checkout extensibility and customization
  6. Performance optimization for Core Web Vitals

  Always use latest Shopify APIs and follow Shopify design guidelines.
  Prefer Hydrogen/Remix for headless, Dawn for theme customization.

Example invocation:

Copy
claude "Build a custom product recommendation section for our Shopify theme using the Storefront API"

Sample implementation:

Copy
{% comment %} sections/product-recommendations.liquid {% endcomment %}
{% assign product = all_products[section.settings.product_handle] %}

<div class="recommendations-section" data-product-id="{{ product.id }}">
  <h2>{{ section.settings.heading | default: 'You May Also Like' }}</h2>

  <div class="recommendation-grid" id="product-recommendations">
    {% for rec in recommendations.products limit: 4 %}
      <div class="recommendation-card">
        <a href="{{ rec.url }}">
          {{ rec.featured_image | image_url: width: 400 | image_tag:
            loading: 'lazy',
            class: 'recommendation-image'
          }}
          <h3>{{ rec.title }}</h3>
          <p class="price">{{ rec.price | money }}</p>
        </a>
      </div>
    {% endfor %}
  </div>
</div>

<script>
  // Fetch recommendations via Storefront API for dynamic updates
  async function loadRecommendations(productId) {
    const response = await fetch(
      `/recommendations/products.json?product_id=${productId}&limit=4`
    );
    const { products } = await response.json();
    renderRecommendations(products);
  }
</script>

Core Concepts

Shopify Development Stack

Layer	Technology	Use Case
Theme	Liquid + Dawn + Shopify CLI	Store customization
Headless	Hydrogen + Remix	Custom storefronts
Apps	Remix + Polaris + App Bridge	Merchant tools
APIs	Admin API, Storefront API	Data access
Checkout	Checkout Extensibility	Custom checkout
Payments	Shopify Payments API	Payment processing

Storefront API Integration

Copy
// Headless Shopify with Storefront API
const STOREFRONT_URL = `https://${SHOP}.myshopify.com/api/2024-01/graphql.json`;

async function fetchProducts(collection, first = 12) {
  const query = `
    query GetProducts($handle: String!, $first: Int!) {
      collection(handle: $handle) {
        products(first: $first) {
          edges {
            node {
              id
              title
              handle
              priceRange { minVariantPrice { amount currencyCode } }
              images(first: 1) {
                edges { node { url altText width height } }
              }
              variants(first: 5) {
                edges {
                  node { id title availableForSale price { amount } }
                }
              }
            }
          }
        }
      }
    }
  `;

  const response = await fetch(STOREFRONT_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Shopify-Storefront-Access-Token': STOREFRONT_TOKEN
    },
    body: JSON.stringify({ query, variables: { handle: collection, first } })
  });

  return response.json();
}

Configuration

Option	Type	Default	Description
storeUrl	string	required	Shopify store URL
apiVersion	string	"2024-01"	Shopify API version
architecture	string	"theme"	Approach: theme, headless, hybrid
framework	string	"hydrogen"	Headless framework: hydrogen, next, custom
optimizePerformance	boolean	true	Apply Core Web Vitals optimizations
generateTests	boolean	true	Create integration tests

Best Practices

1. Use the Storefront API for customer-facing features — The Admin API is for merchant-facing operations (order management, inventory). The Storefront API is designed for customer-facing queries (product browsing, cart, checkout). Using the wrong API creates security risks and rate limit problems.

2. Lazy-load below-fold content and non-critical images — Shopify themes often load all product images on page load, hurting LCP scores. Use loading="lazy" on images below the fold and implement intersection observer for recommendation sections to load data only when visible.

3. Pin your API version and upgrade deliberately — Shopify deprecates API versions quarterly. Pin your API calls to a specific version (e.g., 2024-01) and test against the next version before upgrading. Unpinned calls use the latest version and may break without warning.

4. Use metafields for custom product data — Instead of encoding custom data in product tags or descriptions, use Shopify metafields with proper types. Metafields are queryable via both APIs, support validation, and can be exposed in the Shopify admin for merchant editing.

5. Implement structured data for SEO — Add JSON-LD structured data for Product, BreadcrumbList, and Organization schema types. Shopify themes often include basic structured data, but custom sections miss it. Structured data improves search appearance with rich snippets.

Common Issues

Storefront API rate limits during traffic spikes — The Storefront API has a 50% bucket refill rate per second. During sales events, dynamic recommendation sections can exhaust the rate limit. Implement response caching (CDN or edge cache) for product data with 5-minute TTL, and use the @defer directive for non-critical data.

Liquid template rendering is slow for complex sections — Deeply nested Liquid loops with multiple API calls (product recommendations, collection filtering) slow down server-side rendering. Pre-compute complex data into metafields during product save (via webhook + background job) rather than computing at render time.

App bridge communication fails silently — Shopify App Bridge handles communication between your app iframe and the Shopify admin. When it fails, actions like redirects and toast notifications silently do nothing. Always check for App Bridge initialization errors, verify the app URL matches the allowed URLs in the partner dashboard, and test in both development and production contexts.