Prerequisites:

• A Shopify store (or Shopify Partner account)
• Shopify CLI installed locally
• A theme in a Git repository
• A DeployHQ account

What is Shopify Theme Deployment?

Shopify themes control the look and functionality of a Shopify store. Unlike traditional web deployment where you upload files to a server, Shopify themes are deployed through Shopify's Theme Access API — files are pushed to Shopify's infrastructure, not your own server.

DeployHQ has native Shopify protocol support, making it the simplest way to automate theme deployments from Git.

Step 1: Local Theme Development

Install Shopify CLI: bash npm install -g @shopify/cli @shopify/theme

Pull an existing theme or create a new one: ```bash

Pull existing theme

shopify theme pull --store your-store.myshopify.com

Or create from scratch

shopify theme init my-theme ```

Start local development: bash shopify theme dev --store your-store.myshopify.com

This serves the theme locally with hot reload, proxying data from your live store.

Step 2: Theme Structure

my-theme/
├── assets/              # CSS, JS, images, fonts
│   ├── theme.css
│   └── theme.js
├── config/              # Theme settings
│   ├── settings_schema.json   # Setting definitions
│   └── settings_data.json     # Setting values (⚠️ see note below)
├── layout/              # Layout templates
│   └── theme.liquid
├── locales/             # Translation files
│   └── en.default.json
├── sections/            # Theme sections (modular blocks)
│   ├── header.liquid
│   ├── footer.liquid
│   └── featured-collection.liquid
├── snippets/            # Reusable template fragments
│   └── product-card.liquid
├── templates/           # Page templates
│   ├── index.json       # Home page
│   ├── product.json     # Product page
│   └── collection.json  # Collection page
└── .gitignore

Important: settings_data.json

config/settings_data.json contains the merchant's customisations (colours, fonts, section ordering). This file is frequently edited through the Shopify admin, creating merge conflicts if deployed from Git.

Recommendation: Add config/settings_data.json to your deploy exclusions in DeployHQ. Deploy code changes only; let the merchant manage settings through the admin.

Step 3: Version Control Best Practices

.gitignore: gitignore node_modules/ .shopify/

What to commit: - All Liquid templates, sections, snippets, and layouts - CSS, JavaScript, and asset files - config/settings_schema.json (setting definitions) - Locale files - Theme JSON templates

What to consider excluding from deployment: - config/settings_data.json — merchant customisations that should persist on the store

Step 4: Deploy with DeployHQ

Create a DeployHQ Project

1. Sign up at deployhq.com
2. Create a new project and connect your Git repository

Add a Shopify Server

Go to Servers → New Server:

• Protocol: Shopify
• Store URL: your-store.myshopify.com
• Theme Access Password: Generate this in Shopify admin under Online Store → Themes → ⋯ → Edit code → Theme Access

Alternatively, use the Theme Access app: 1. Install the Theme Access app from the Shopify App Store 2. Generate a password for DeployHQ 3. Enter the password in DeployHQ's server configuration

Select the Target Theme

DeployHQ lets you choose which theme to deploy to. Options: - Published theme — your live, customer-facing theme - Unpublished theme — a draft theme for testing - Specific theme by ID — useful for staging workflows

Configure Excluded Files

Under server settings, add exclusions: config/settings_data.json

This prevents deployment from overwriting merchant customisations.

No Build Commands Needed

Shopify processes Liquid templates server-side. There's no build step — files are deployed as-is.

If your theme uses a CSS preprocessor or JavaScript bundler locally, commit the compiled output to Git: json { "scripts": { "build": "npm run build:css && npm run build:js", "build:css": "postcss src/css/theme.css -o assets/theme.css", "build:js": "esbuild src/js/theme.js --bundle --outfile=assets/theme.js" } }

Run npm run build locally before committing, or add it as a DeployHQ build command if you prefer server-side builds.

Automatic Deployment

DeployHQ installs a webhook on your Git repository. Every push to the configured branch triggers a deployment to Shopify.

Step 5: Multi-Environment Workflow

Map Git branches to different Shopify themes:

In DeployHQ, create two servers — one pointing to the published theme (triggered by main) and one pointing to the development theme (triggered by develop).

Workflow: 1. Create feature branch, develop locally with shopify theme dev 2. Merge to develop → auto-deploys to development theme for QA 3. Merge to main → auto-deploys to live theme

Step 6: Troubleshooting

Theme Access Password Not Working

• Ensure the password hasn't expired
• Regenerate if needed from Shopify admin
• Check that the password grants access to the specific theme you're targeting

settings_data.json Conflicts

If you accidentally deploy settings_data.json, the merchant's customisations will be overwritten. To fix: 1. Add the file to DeployHQ's exclusion list 2. In Shopify admin, re-apply customisations or restore from a theme backup

Asset Size Limits

Shopify has a 20MB limit per individual asset file and 100MB total theme size. If deployment fails: - Optimise images before committing - Use external CDN for large media files - Check total theme size: shopify theme info

Deployment Takes Too Long

Shopify's API has rate limits. Large themes with many files may take several minutes on first deployment. Subsequent deployments transfer only changed files, which is much faster.

Conclusion

DeployHQ's native Shopify protocol eliminates the complexity of theme deployment. Push to Git, and your theme updates are live — no CLI commands, no manual uploads, no risk of forgetting files.

For more Shopify deployment tips, see our Shopify blog posts.

Sign up for DeployHQ — free for one project.

Questions? Contact support@deployhq.com or on Twitter/X.