Initial commit
This commit is contained in:
Zhongwei Li
417
skills/shopify-workflow-tools/SKILL.md
Normal file
417
skills/shopify-workflow-tools/SKILL.md
Normal file
@@ -0,0 +1,417 @@
|
||||
---
|
||||
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
|
||||
```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
|
||||
```
|
||||
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
|
||||
|
||||
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.
|
||||
Reference in New Issue
Block a user