Skip to main content
This guide covers the recommended development workflow and best practices for working with Horizon.

​
Development Philosophy

Horizon follows these core principles:

Web-Native

Leverage the latest web browsers to their fullest, while maintaining support for older ones through progressive enhancement—not polyfills.

Lean and Fast

Functionality and design defaults to “no” until it meets quality requirements. Code ships on quality.

Server-Rendered

HTML must be rendered by Shopify servers using Liquid. Business logic and platform primitives belong on the server.

Functional, Not Pixel-Perfect

Use semantic markup, progressive enhancement, and clever design to ensure themes remain functional regardless of browser.

​
Daily Development Workflow

1

Start the development server

Begin each session by starting the local development server:
shopify theme dev
This command:
  • Uploads your theme to your development store
  • Starts a local server at http://127.0.0.1:9292
  • Watches for file changes and syncs them automatically
  • Provides hot reload functionality
2

Make your changes

Edit theme files in your code editor. Changes are automatically synced to your development store.Common files you’ll work with:
  • /templates/*.liquid - Page templates
  • /sections/*.liquid - Reusable sections
  • /snippets/*.liquid - Smaller reusable components
  • /blocks/*.liquid - Theme blocks
  • /assets/*.css - Stylesheets
  • /assets/*.js - JavaScript files
3

Test in the browser

Preview changes in real-time using the local preview URL or the theme editor preview link.
4

Validate your code

Run Theme Check to catch issues:
shopify theme check
5

Commit your changes

Commit working changes to version control:
git add .
git commit -m "Add product quick view feature"

​
Working with Git

​
Staying Up to Date with Horizon Changes

If you’re building a theme based on Horizon and want to pull in the latest changes:
1

Navigate to your theme folder

cd your-theme-directory
2

Verify your remotes

Check that you have both origin and upstream remotes:
git remote -v
Expected output:
origin    https://github.com/your-username/your-theme.git (fetch)
origin    https://github.com/your-username/your-theme.git (push)
upstream  https://github.com/Shopify/horizon.git (fetch)
upstream  https://github.com/Shopify/horizon.git (push)
3

Add upstream remote (if needed)

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

Pull latest changes

Fetch and merge the latest Horizon changes:
git fetch upstream
git pull upstream main
Resolve any merge conflicts if they occur.
Pulling upstream changes may introduce breaking changes. Always test thoroughly after merging.

​
Theme Structure Best Practices

​
Server-First Development

  • Business logic belongs on the server: Use Liquid for translations, money formatting, and platform primitives
  • Progressive enhancement: Start with working HTML, then enhance with JavaScript
  • Minimal client-side rendering: Async rendering is OK, but use it sparingly

​
Code Organization

  • Sections for major components: Use sections for reusable, configurable components
  • Snippets for shared markup: Extract common HTML patterns into snippets
  • Theme blocks for flexibility: Leverage theme blocks for customizable layouts

​
Performance Considerations

  • Lean by default: Only add features that are necessary
  • Optimize assets: Minify CSS and JavaScript
  • Lazy load when appropriate: Defer non-critical resources
  • Use native browser features: Avoid polyfills when possible

​
Testing Your Theme

​
Manual Testing Checklist

  • Test on multiple browsers (Chrome, Firefox, Safari, Edge)
  • Test responsive design on various screen sizes
  • Test with different theme settings
  • Verify accessibility with keyboard navigation
  • Check performance with browser DevTools

​
Automated Validation

# Run Theme Check for Liquid validation
shopify theme check

# Check specific files or directories
shopify theme check templates/product.liquid

​
Deployment Workflow

1

Final validation

Run a complete theme check:
shopify theme check
Ensure all issues are resolved before deploying.
2

Push to a new theme

Upload your theme to the store without making it live:
shopify theme push --unpublished
This creates a new theme you can preview and test.
3

Test the uploaded theme

Test the theme thoroughly on your store before publishing.
4

Publish the theme

When ready, publish from the Shopify admin or use:
shopify theme publish

​
Common Development Tasks

​
Adding a New Section

  1. Create a new .liquid file in /sections/
  2. Define the section schema with settings
  3. Test in the theme editor
  4. Run Theme Check to validate

​
Modifying Styles

  1. Edit CSS files in /assets/
  2. Changes sync automatically with shopify theme dev
  3. Test responsive breakpoints
  4. Verify progressive enhancement

​
Working with Locales

  1. Edit translation files in /locales/
  2. Use Liquid translation filters: {{ 'key' | t }}
  3. Test with different locale settings

​
Troubleshooting Tips

​
Changes Not Appearing

  1. Check the CLI output for sync errors
  2. Hard refresh your browser (Cmd/Ctrl + Shift + R)
  3. Verify the file is being watched (not in .shopifyignore)
  4. Restart the development server

​
Theme Check Errors

  1. Read the error message carefully
  2. Check the Theme Check documentation
  3. Fix issues incrementally
  4. Re-run validation after each fix

​
Merge Conflicts with Upstream

  1. Identify conflicting files
  2. Manually resolve conflicts in your editor
  3. Test thoroughly after resolving
  4. Commit the resolved changes

​
Next Steps

Shopify CLI Reference

Complete guide to Shopify CLI commands

Theme Check

Learn about validation and linting

Customization

Customize Horizon for your needs

Contributing

Learn about contributing to Horizon

Build docs developers (and LLMs) love

Get started for freeTalk to us