Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Shopify/horizon/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

This guide helps you safely migrate your Horizon theme to the latest version while preserving your customizations and store settings.
Always test theme updates on a development or staging store before applying them to your live production store.

​
Before You Begin

1

Backup your current theme

Download a copy of your current theme from the Shopify admin:
  1. Navigate to Online Store > Themes
  2. Find your current theme
  3. Click Actions > Download theme file
  4. Save the .zip file in a safe location
2

Review the release notes

Check the release notes to understand what’s changed in the new version and identify potential breaking changes.
3

Prepare a test environment

Create a duplicate of your store or use a development store to test the migration before applying it to production.

​
Migration Methods

​
Method 1: Pulling Upstream Changes (Recommended)

If you’re using Git to manage your theme, you can pull the latest changes from the Horizon repository.
1

Navigate to your local theme folder

cd /path/to/your/theme
2

Verify your remotes

Check that you have both origin and upstream configured:
git remote -v
You should see:
  • origin - your repository
  • upstream - Shopify’s Horizon repository
3

Add upstream remote if needed

If you don’t see an upstream remote, add one pointing to Shopify’s Horizon repository:
git remote add upstream https://github.com/Shopify/horizon.git
4

Fetch and pull the latest changes

git fetch upstream
git pull upstream main
This may result in merge conflicts if you’ve modified core theme files. You’ll need to resolve these conflicts manually.
5

Resolve merge conflicts

If you encounter conflicts:
  1. Open each conflicted file in your code editor
  2. Look for conflict markers (<<<<<<<, =======, >>>>>>>)
  3. Decide which changes to keep (yours, upstream, or both)
  4. Remove the conflict markers
  5. Test the resolved code
# After resolving conflicts
git add .
git commit -m "Merge upstream Horizon changes"

​
Method 2: Manual File Comparison

For smaller updates or if you’re not using Git:
1

Download the latest Horizon release

git clone https://github.com/Shopify/horizon.git
2

Compare settings files

Use a diff tool to compare:
  • config/settings_schema.json
  • config/settings_data.json (your customizations)
  • Section schema files in sections/
3

Update modified files

Carefully copy updates from new files to your theme, preserving your customizations.
4

Test thoroughly

Test all pages and functionality before deploying.

​
Version-Specific Migration Notes

​
Migrating to v3.4.0

The account menu has been replaced with a new web component version.Action required:
  • Test all customer account functionality
  • Verify login, logout, and account navigation work correctly
  • Check that any custom account-related CSS still applies
New settings allow control over product card widths on desktop and mobile.Action required:
  • Review product grids on collection pages
  • Adjust new width settings in section configurations if needed
  • Test responsive behavior on various screen sizes
Footer and header elements now use proper semantic HTML and ARIA roles.Action required:
  • If you’ve customized header or footer markup, update to use semantic elements
  • Test with screen readers to ensure accessibility is maintained

​
Post-Migration Checklist

After updating, verify the following:
  • Homepage loads correctly
  • Collection pages display products properly
  • Product pages show all variants and media
  • Cart and checkout flow works
  • Search functionality operates correctly
  • Customer account login/logout works
  • Mobile navigation functions properly
  • Color schemes are correct
  • Typography matches your brand
  • Logo displays at the right size
  • Images load with correct sizing
  • Spacing and layout look appropriate
  • Custom CSS is still applied
  • Page load times are acceptable
  • Images are optimized and loading
  • No console errors in browser DevTools
  • Theme Check passes without critical errors
  • Chrome/Edge (Chromium)
  • Firefox
  • Safari (macOS and iOS)
  • Mobile browsers (iOS Safari, Chrome)

​
Troubleshooting

If you encounter issues after migration:
  1. Clear cache: Clear your browser cache and Shopify’s theme cache
  2. Check Theme Check: Run shopify theme check to identify problems
  3. Review console: Check browser DevTools for JavaScript errors
  4. Compare files: Use a diff tool to compare your customized files with the upstream version
  5. Rollback if needed: Restore your backup theme if critical issues arise
For more help, see the Troubleshooting guide.

​
Rolling Back

If you need to revert to your previous theme version:
1

From Shopify Admin

  1. Go to Online Store > Themes
  2. In the Theme library, find your backup theme
  3. Click Actions > Publish
2

From Git

git log  # Find the commit hash before the merge
git reset --hard <commit-hash>
git push origin main --force  # Use with caution
Force pushing can overwrite history. Make sure you have backups before using git push --force.

​
Best Practices

  • Never modify core theme files directly - Use custom sections and snippets instead
  • Document your changes - Keep notes on customizations you’ve made
  • Update regularly - Don’t fall too far behind on updates
  • Test on development stores - Always test updates before going live
  • Use version control - Git makes migrations much easier

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us