shopify-workflow-tools

name	Shopify Workflow & Tools
description	Shopify CLI commands, development workflow, and essential tools for theme development

Shopify Workflow & Tools

Shopify CLI Commands

Initialize a New Theme

# 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

# 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

# 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

# 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

# Publish theme
shopify theme publish --theme=THEME_ID

# List all themes
shopify theme list

Delete Theme

shopify theme delete --theme=THEME_ID

Check Theme for Issues

# Run theme check
shopify theme check

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

Development Workflow

1. Initial Setup

# 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

# 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

# Check for theme issues
shopify theme check

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

4. Deploy to Shopify

# 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

# 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

npm install -g @shopify/theme-check

Usage

# 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

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

# 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

# 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

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

{%- assign debug = true -%}

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

Console Logging

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

Theme Check Output

# Verbose output
shopify theme check --verbose

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

Performance Optimization

Image Optimization

{%- # 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

{%- # 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

{%- # 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

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

# 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

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

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

Authentication Issues

# Re-authenticate
shopify auth logout
shopify auth login

Theme Push Conflicts

# 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

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

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