Shopify Development Toolkit

A comprehensive Shopify development skill covering theme development with Liquid, custom sections, Shopify CLI workflows, and storefront optimization for performance and conversion.

When to Use

Choose Shopify Development Toolkit when:

• Developing custom Shopify themes with Liquid templating
• Building theme sections and blocks for the Online Store editor
• Optimizing storefront performance and conversion rates
• Customizing Shopify's checkout and cart functionality

Consider alternatives when:

• Building a Shopify app — use the Shopify App framework
• Creating a headless storefront — use the Storefront API with React/Next.js
• Simple theme changes — use the Shopify theme editor directly

Quick Start

Copy
# Initialize a new Shopify theme
shopify theme init my-theme
cd my-theme

# Start development server with hot reload
shopify theme dev --store=mystore.myshopify.com

# Pull existing theme
shopify theme pull --store=mystore.myshopify.com

Copy
{% comment %}
  sections/featured-collection.liquid - Custom section with schema
{% endcomment %}

<div class="featured-collection" data-section-id="{{ section.id }}">
  <div class="container">
    {% if section.settings.title != blank %}
      <h2 class="section-title">{{ section.settings.title }}</h2>
    {% endif %}

    {% if section.settings.collection != blank %}
      {% assign collection = collections[section.settings.collection] %}
      <div class="product-grid" style="--columns: {{ section.settings.columns }}">
        {% for product in collection.products limit: section.settings.products_to_show %}
          <div class="product-card">
            <a href="{{ product.url }}">
              {% if product.featured_image %}
                <img
                  src="{{ product.featured_image | image_url: width: 600 }}"
                  alt="{{ product.featured_image.alt | escape }}"
                  loading="lazy"
                  width="600"
                  height="{{ 600 | divided_by: product.featured_image.aspect_ratio }}"
                >
              {% endif %}
              <h3>{{ product.title }}</h3>
              <p class="price">{{ product.price | money }}</p>
              {% if product.compare_at_price > product.price %}
                <span class="sale-badge">Sale</span>
              {% endif %}
            </a>
          </div>
        {% endfor %}
      </div>
    {% endif %}
  </div>
</div>

{% schema %}
{
  "name": "Featured Collection",
  "settings": [
    {
      "type": "text",
      "id": "title",
      "label": "Section Title",
      "default": "Featured Products"
    },
    {
      "type": "collection",
      "id": "collection",
      "label": "Collection"
    },
    {
      "type": "range",
      "id": "products_to_show",
      "min": 2,
      "max": 12,
      "step": 1,
      "default": 4,
      "label": "Products to show"
    },
    {
      "type": "range",
      "id": "columns",
      "min": 2,
      "max": 5,
      "step": 1,
      "default": 4,
      "label": "Columns"
    }
  ],
  "presets": [
    {
      "name": "Featured Collection"
    }
  ]
}
{% endschema %}

Core Concepts

Shopify Theme Architecture

Directory	Purpose	Files
layout/	Page wrappers	theme.liquid, password.liquid
templates/	Page type templates	product.json, collection.json
sections/	Reusable page sections	Custom .liquid files
snippets/	Reusable code fragments	Partials, helpers
assets/	Static files	CSS, JS, images
config/	Theme settings	settings_schema.json
locales/	Translations	en.default.json

Performance Optimization

Copy
{% comment %} Optimized product image loading {% endcomment %}
{%- assign image = product.featured_image -%}
<picture>
  <source
    media="(min-width: 768px)"
    srcset="{{ image | image_url: width: 800 }} 800w,
            {{ image | image_url: width: 1200 }} 1200w"
    sizes="(min-width: 1200px) 400px, 50vw"
  >
  <source
    srcset="{{ image | image_url: width: 400 }} 400w,
            {{ image | image_url: width: 600 }} 600w"
    sizes="100vw"
  >
  <img
    src="{{ image | image_url: width: 600 }}"
    alt="{{ image.alt | escape }}"
    loading="{% if forloop.first %}eager{% else %}lazy{% endif %}"
    width="{{ image.width }}"
    height="{{ image.height }}"
    fetchpriority="{% if forloop.first %}high{% else %}auto{% endif %}"
  >
</picture>

Configuration

Option	Description	Default
store_url	Shopify store URL	Required
theme_id	Target theme ID	Active theme
api_version	Shopify API version	Latest stable
dev_port	Local development port	9292
hot_reload	Enable hot module reload	true
ignore_files	Files to exclude from sync	["config/settings_data.json"]
notify_file	Browser notification endpoint	Auto
live_reload	Full page reload on change	"full-page"

Best Practices

1. Use JSON templates instead of Liquid templates for page types so merchants can customize page layouts through the theme editor without code changes
2. Optimize Largest Contentful Paint by setting fetchpriority="high" on hero images, preloading critical fonts, and inlining critical CSS above the fold
3. Use Shopify's built-in image transformations with image_url filter instead of uploading multiple image sizes — Shopify's CDN handles resizing, compression, and WebP conversion automatically
4. Implement proper section schemas with clear labels, helpful defaults, and logical grouping so merchants can configure sections without developer assistance
5. Version control everything except settings_data.json because this file contains merchant customizations that should not be overwritten during deployments

Common Issues

Theme editor changes overwritten by deployment: Deploying a theme overwrites settings_data.json with the development version. Add config/settings_data.json to .shopifyignore and use shopify theme push --ignore=config/settings_data.json for deployments.

Liquid rendering performance on collection pages: Collections with hundreds of products and heavy Liquid logic cause slow server-side rendering. Paginate collections to 24-48 products, avoid nested loops in Liquid, and use AJAX loading for additional products rather than rendering everything server-side.

Section JavaScript not initializing after dynamic loading: When sections load via AJAX (theme editor, section rendering API), their JavaScript does not execute. Listen for the shopify:section:load event on document and initialize section-specific JavaScript in the handler rather than on DOMContentLoaded.