Shopify Workflow & Tools

Shopify CLI Commands

Initialize a New Theme

bash

# Clone the Dawn reference theme
shopify theme init

# Clone a specific theme
shopify theme init --clone-url https://github.com/Shopify/dawn.git

Development Server

bash

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

# Development server options
shopify theme dev --store=example.myshopify.com --port=9293
shopify theme dev --store=example.myshopify.com --theme-editor-sync

Features:

•Hot-reload for CSS and sections
•Live preview at http://127.0.0.1:9292
•Syncs with theme editor changes
•Chrome browser recommended

Push Theme to Shopify

bash

# Push as unpublished theme (recommended first push)
shopify theme push --unpublished

# Push to specific theme
shopify theme push --theme=THEME_ID

# Push with development flag
shopify theme push --development

Pull Theme from Shopify

bash

# Pull published theme
shopify theme pull

# Pull specific theme
shopify theme pull --theme=THEME_ID

# Pull only specific files
shopify theme pull --only=templates/*.json,sections/*.liquid

Publish Theme

bash

# Publish theme
shopify theme publish --theme=THEME_ID

# List all themes
shopify theme list

Delete Theme

bash

shopify theme delete --theme=THEME_ID

Check Theme for Issues

bash

# Run theme check
shopify theme check

# Auto-fix issues
shopify theme check --auto-correct

Development Workflow

1. Initial Setup

bash

# Clone starter theme
shopify theme init

# Navigate to theme directory
cd your-theme-name

# Install dependencies (if using package.json)
npm install

# Start development
shopify theme dev --store=your-store.myshopify.com

2. Local Development

bash

# Start dev server
shopify theme dev --store=example.myshopify.com

# Open browser to http://127.0.0.1:9292
# Make changes to Liquid, CSS, JavaScript
# See changes instantly (hot-reload for CSS/sections)

3. Testing & Validation

bash

# Check for theme issues
shopify theme check

# Fix auto-fixable issues
shopify theme check --auto-correct

4. Deploy to Shopify

bash

# First deployment (as unpublished)
shopify theme push --unpublished

# Or push to development theme
shopify theme push --development

# Verify in Shopify admin
# Theme Library > View theme

5. Publishing

bash

# List themes to get THEME_ID
shopify theme list

# Publish theme
shopify theme publish --theme=THEME_ID

Theme Check

Shopify's official linting tool for themes.

Install

bash

npm install -g @shopify/theme-check

Usage

bash

# Run checks
theme-check .

# Auto-fix issues
theme-check . --auto-correct

# Check specific files
theme-check sections/header.liquid

Common Checks

•Liquid syntax errors
•Performance issues
•Accessibility problems
•Deprecated tags/filters
•Missing translations
•Asset optimization

Integration with VS Code

Install the "Shopify Liquid" extension for:

•Real-time linting
•Syntax highlighting
•Autocomplete
•Hover documentation

File Structure

Required Files

code

your-theme/
├── config/
│   ├── settings_schema.json    # Global theme settings (required)
│   └── settings_data.json      # Theme setting values (auto-generated)
├── layout/
│   └── theme.liquid             # Base layout (required)
├── templates/
│   ├── index.json               # Homepage template (required)
│   ├── product.json             # Product page template
│   ├── collection.json          # Collection page template
│   └── 404.liquid               # 404 page
├── sections/
│   └── *.liquid                 # Reusable sections
├── snippets/
│   └── *.liquid                 # Reusable code fragments
├── assets/
│   └── *.*                      # CSS, JS, images, fonts
└── locales/
    └── en.default.json          # Default language (required)

Environment Best Practices

Development Stores

•Free for Partners
•Sandbox for testing
•No impact on production
•Can transfer to client

bash

# Create development store
# Visit partners.shopify.com
# Stores > Add store > Development store

Theme Environments

•Development: shopify theme dev or --development flag
•Staging/Preview: --unpublished flag
•Production: Published theme

Version Control

bash

# Initialize git
git init

# Add .gitignore
echo "config/settings_data.json" >> .gitignore
echo "node_modules/" >> .gitignore
echo ".DS_Store" >> .gitignore

# Commit theme
git add .
git commit -m "Initial theme commit"

Important: .gitignore should exclude:

•config/settings_data.json (store-specific)
•node_modules/ (dependencies)
•.DS_Store (macOS files)

Debugging Techniques

Liquid Debugging

liquid

{%- comment -%}
  Debug output using assign and display
{%- endcomment -%}

{%- assign debug = true -%}

{%- if debug -%}
  <pre>
    Product: {{ product | json }}
    Cart: {{ cart | json }}
  </pre>
{%- endif -%}

Console Logging

liquid

{% javascript %}
  console.log('Product data:', {{ product | json }});
  console.log('Settings:', {{ section.settings | json }});
{% endjavascript %}

Theme Check Output

bash

# Verbose output
shopify theme check --verbose

# Output to file
shopify theme check > check-results.txt

Performance Optimization

Image Optimization

liquid

{%- # Use appropriate image sizes -%}
<img
  srcset="
    {{ image | image_url: width: 400 }} 400w,
    {{ image | image_url: width: 800 }} 800w,
    {{ image | image_url: width: 1200 }} 1200w
  "
  sizes="(min-width: 1024px) 33vw, (min-width: 768px) 50vw, 100vw"
  src="{{ image | image_url: width: 800 }}"
  loading="lazy"
>

Asset Loading

liquid

{%- # Defer non-critical JavaScript -%}
<script src="{{ 'theme.js' | asset_url }}" defer></script>

{%- # Preload critical assets -%}
<link rel="preload" href="{{ 'theme.css' | asset_url }}" as="style">

Minimize Liquid Logic

liquid

{%- # Good - assign complex logic to variable -%}
{%- liquid
  assign is_on_sale = false
  if product.compare_at_price > product.price
    assign is_on_sale = true
  endif
-%}

{%- if is_on_sale -%}
  <span>On Sale</span>
{%- endif -%}

{%- # Bad - inline complex logic -%}
{% if product.compare_at_price > product.price %}
  <span>On Sale</span>
{% endif %}

CI/CD Integration

GitHub Actions Example

yaml

name: Deploy Theme

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Shopify CLI
        run: npm install -g @shopify/cli @shopify/theme
      - name: Push theme
        run: shopify theme push --development
        env:
          SHOPIFY_CLI_THEME_TOKEN: ${{ secrets.SHOPIFY_CLI_THEME_TOKEN }}

Common Commands Reference

bash

# Authentication
shopify auth login

# Theme commands
shopify theme list                    # List all themes
shopify theme info                    # Show theme info
shopify theme dev                     # Start dev server
shopify theme push                    # Push theme
shopify theme pull                    # Pull theme
shopify theme publish                 # Publish theme
shopify theme delete                  # Delete theme
shopify theme check                   # Check theme for issues
shopify theme package                 # Package theme as .zip

# Theme check
theme-check .                         # Run checks
theme-check . --auto-correct          # Fix issues
theme-check . --config=.theme-check.yml  # Use custom config

# Help
shopify theme --help                  # Show help
shopify theme dev --help              # Show dev command help

Troubleshooting

Development Server Not Starting

bash

# Check if port is in use
lsof -i :9292

# Use different port
shopify theme dev --port=9293

Authentication Issues

bash

# Re-authenticate
shopify auth logout
shopify auth login

Theme Push Conflicts

bash

# Force push (caution: overwrites remote)
shopify theme push --force

# Pull first, then push
shopify theme pull
shopify theme push

Hot Reload Not Working

•Ensure using Chrome browser
•Check file paths are correct
•Restart dev server
•Clear browser cache

Best Practices

•Use development stores for testing
•Push unpublished first before publishing
•Run theme check before deploying
•Use version control (Git)
•Exclude settings_data.json from Git
•Test on multiple devices before publishing
•Keep CLI updated: npm update -g @shopify/cli
•Use theme editor sync during development
•Document custom features in README
•Follow Shopify theme requirements for Theme Store

Use these tools and workflows to build, test, and deploy Shopify themes efficiently.