Shopify Developer

Expert guidance for Shopify development across themes, headless commerce, and platform extensions.

Recommended: Install Context7 Skill

For up-to-date Shopify documentation lookups, install the Context7 skill:

npx skills add intellectronica/agent-skills --skill context7

This enables real-time API verification to prevent outdated patterns.

Workflow Decision Tree

Theme Development (Liquid)

→ Consult liquid-patterns.md for metafields, loops, and performance.

• New section/template: Create section with schema, use sections everywhere architecture
• Editing existing theme: Pull latest first, push to draft, test before live
• Performance issues: Minimize loops, use limit:, cache expensive lookups

Headless Commerce (Hydrogen)

→ Consult apis-functions.md for Storefront API queries and components.

• New storefront: Use Hydrogen 2.0 + Oxygen hosting
• Custom checkout: Use Checkout Extensibility (checkout.liquid is deprecated)

Backend Logic (Functions)

→ Consult apis-functions.md for Function examples.

• Custom discounts, shipping, payments: Shopify Functions (<5ms execution, Plus only)
• Workflow automation: Shopify Flow

Store-Specific Work

• BestSelf.co: Invoke BestSelf-Shopify-Skill for theme IDs, 42- section patterns, CSS conventions

The API Drift Test

CRITICAL: Before implementing ANY Shopify feature, verify current patterns using Context7:

# Find Shopify Liquid library
curl -s "https://context7.com/api/v2/libs/search?libraryName=shopify+liquid&query=metafields" | jq '.results[0].id'

# Fetch current documentation
curl -s "https://context7.com/api/v2/context?libraryId=/shopify/liquid&query=metafield+access&type=txt"

Common lookups:

• Liquid: libraryName=shopify+liquid
• Storefront API: libraryName=shopify+storefront+api
• Hydrogen: libraryName=shopify+hydrogen

Why this matters: Shopify APIs change frequently. Code that worked in 2024 may be deprecated in 2025.

Also check: https://changelog.shopify.com for breaking changes.

Liquid Development

→ Consult liquid-patterns.md for complete patterns.

Quick Reference

{% comment %} Metafield (always use .value) {% endcomment %}
{{ product.metafields.custom.subtitle.value }}

{% comment %} List metafield iteration {% endcomment %}
{% for item in product.metafields.features.highlights.value %}
  {{ item }}
{% endfor %}

{% comment %} Metaobject iteration {% endcomment %}
{% for item in shop.metaobjects.testimonials.values %}
  {{ item.title }}
{% endfor %}

{% comment %} Safe defaults {% endcomment %}
{{ section.settings.title | default: 'Default Title' }}

DO / DON’T

DO: Use .value accessor for metafields DO: Use limit: on loops to prevent performance issues DO: Use where: filter instead of nested conditionals DO: Cache expensive lookups with {% assign %}

DON’T: Nest loops without limits—exponential performance hit DON’T: Use checkout.liquid—deprecated Aug 2024 DON’T: Edit settings_data.json manually—Theme Editor overwrites it DON’T: Forget shopify_attributes on blocks—breaks Theme Editor

Section Architecture

→ Consult section-settings.md for all 20+ setting types.

Section Schema Template

{% schema %}
{
  "name": "Section Name",
  "tag": "section",
  "class": "section-class",
  "settings": [
    { "type": "text", "id": "title", "label": "Title", "default": "Hello" },
    { "type": "richtext", "id": "content", "label": "Content" }
  ],
  "blocks": [
    {
      "type": "item",
      "name": "Item",
      "settings": [
        { "type": "text", "id": "heading", "label": "Heading" }
      ]
    }
  ],
  "presets": [{ "name": "Section Name" }]
}
{% endschema %}

DO: Include presets for sections you want in Theme Editor DO: Use shopify_attributes on block containers DON’T: Exceed 25 settings per section DON’T: Exceed 50 blocks per section

APIs & Functions

→ Consult apis-functions.md for complete examples.

Storefront API (GraphQL)

For custom storefronts, cart operations, and product queries. Rate limit: 60 req/sec.

Admin API (GraphQL)

For metafield management, product updates, order operations. Rate limit: 50 points/sec.

Shopify Functions (Plus only)

Custom discounts, delivery, payments. Must execute in <5ms.

Checkout Extensions

Modern checkout customization using React components.

Platform Constraints

→ Consult platform-limits.md for complete limits and 2024-2025 changes.

Theme CLI Workflow

# 1. Always pull latest first
shopify theme pull --theme <live-id>

# 2. Preview locally with hot reload
shopify theme dev --theme <draft-id>

# 3. Push to draft for testing
shopify theme push --theme <draft-id>

# 4. Only push to live after approval
shopify theme push --theme <live-id> --allow-live

# Push specific files only
shopify theme push --theme <id> --only assets/custom.css --only sections/hero.liquid

DO: Pull before starting work—themes change outside your session DO: Push to draft first, test, then push to live DON’T: Push directly to live without testing

Output Checklist

When providing Shopify solutions:

• Verified current API patterns via Context7 or official docs
• Complete Liquid code with proper .value accessors
• Section schema with presets (if creating sections)
• Metafield configuration requirements noted
• Performance considerations (loop limits, caching)
• Testing notes for edge cases (empty states, variants)