**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](https://www.deployhq.com/signup)
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](https://apps.shopify.com/theme-access) 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:

| Branch | Theme | Purpose |
|--------|-------|---------|
| `main` | Published theme (live) | Production |
| `develop` | Unpublished theme "Development" | Testing |
| `feature/*` | — | Local development only |

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](https://www.deployhq.com/blog/category/shopify).

[Sign up for DeployHQ](https://www.deployhq.com/signup) — free for one project.

Questions? Contact [support@deployhq.com](mailto:support@deployhq.com) or on [Twitter/X](https://x.com/deployhq).