Skip to main content

​
Quick Start

Get up and running with Horizon in minutes. This guide will walk you through cloning the repository, installing dependencies, and launching your local development environment.
1

Clone the Repository

Clone the Horizon repository from GitHub to your local machine:
git clone https://github.com/Shopify/horizon.git
cd horizon
This creates a local copy of the Horizon theme in a directory called horizon.
2

Install Shopify CLI

Shopify CLI is essential for theme development. It provides commands for working with themes on a Shopify store and launching a local development server.Install via Homebrew (macOS/Linux):
brew tap shopify/shopify
brew install shopify-cli
Install via npm:
npm install -g @shopify/cli @shopify/theme
Install via Ruby gem:
gem install shopify-cli
Verify the installation:
shopify version
You’ll need Node.js 18+ and npm 8+ for the npm installation method.
3

Connect to a Shopify Store

Authenticate with Shopify and connect your theme to a development store:
shopify theme dev
This command will:
  1. Prompt you to log in to your Shopify Partner account
  2. Let you select or create a development store
  3. Upload your theme to the store
  4. Start a local development server
If you don’t have a development store, you can create one for free in your Shopify Partner account.
4

Start Developing

Once the development server is running, you’ll see output like this:
╭─ Ready ──────────────────────────────────────────────╮
│                                                      │
│  Preview your theme:                                 │
│  • http://127.0.0.1:9292                            │
│                                                      │
│  Customize your theme in the Shopify admin:         │
│  • https://your-store.myshopify.com/admin/themes    │
│                                                      │
│  Share your theme preview:                          │
│  • https://your-store.myshopify.com/?preview_theme  │
│                                                      │
╰──────────────────────────────────────────────────────╯
Open the preview URL in your browser and start making changes. The page will automatically reload when you save files.

​
Development Workflow

​
File Watching & Hot Reload

The Shopify CLI development server watches your theme files and automatically syncs changes to your store:
  • Liquid files (.liquid): Changes are synced and the page reloads
  • Asset files (.js, .css): Changes are synced and the page hot-reloads
  • Config files (.json): Changes are synced and require a manual refresh

​
Theme Editor

While developing, you can use the Shopify theme editor to customize sections and settings: 
# Open the theme editor in your browser
open "https://your-store.myshopify.com/admin/themes/current/editor"
Changes made in the theme editor are automatically saved to your store but not synced back to your local files.
Settings changed in the theme editor must be manually pulled to your local environment using:
shopify theme pull

​
Project Structure

Understanding Horizon’s file structure will help you navigate and customize the theme:

​
Core Directories

Contains all JavaScript, CSS, and static assets. Horizon uses vanilla JavaScript with web components:
assets/
├── component.js                    # Base component class
├── cart-drawer.js                  # Cart drawer component
├── product-media.js                # Product gallery
├── facets.js                       # Collection filtering
└── jsconfig.json                   # JavaScript configuration
JavaScript files are loaded as ES modules with type="module".
Shopify sections that can be added to pages through the theme editor:
sections/
├── header.liquid                   # Site header
├── hero.liquid                     # Hero section
├── featured-product.liquid         # Featured product
├── collection-list.liquid          # Collection grid
└── footer.liquid                   # Site footer
Each section includes its schema for theme editor customization.
Theme blocks that can be used within sections:
blocks/
├── _card.liquid                    # Card component
├── _announcement.liquid            # Announcement bar
├── _blog-post-card.liquid          # Blog post card
└── _accordion-row.liquid           # Accordion item
Blocks are prefixed with _ to distinguish them from sections.
Reusable Liquid code that can be rendered anywhere:
snippets/
├── button.liquid                   # Button component
├── price.liquid                    # Price display
├── product-card.liquid             # Product card
├── theme-styles-variables.liquid   # CSS custom properties
└── color-schemes.liquid            # Color scheme styles
Snippets are included using {% render 'snippet-name' %}.
JSON templates that define the default sections for each page type:
templates/
├── index.json                      # Homepage
├── product.json                    # Product pages
├── collection.json                 # Collection pages
└── article.json                    # Blog post pages
Global theme configuration and settings:
config/
├── settings_schema.json            # Theme setting definitions
└── settings_data.json              # Saved setting values
The settings schema defines what appears in the theme editor.

​
Essential Commands

Here are the most common Shopify CLI commands you’ll use:

​
Development Server

# Start the development server
shopify theme dev

# Start on a specific port
shopify theme dev --port 9293

# Start with live reload disabled
shopify theme dev --no-live-reload

​
Theme Management

# Pull theme files from your store
shopify theme pull

# Push theme files to your store
shopify theme push

# Push and publish as the live theme
shopify theme push --publish

# Check for theme issues
shopify theme check

​
Theme Information

# List all themes on your store
shopify theme list

# Share a preview link
shopify theme share

# Open the theme editor
shopify theme open
Run shopify theme --help to see all available commands and options.

​
Development Tools

Horizon is set up to work with several development tools that enhance your workflow:

​
Theme Check

Theme Check validates and lints your Shopify themes. It’s included in Horizon’s VS Code configuration. Run Theme Check: 
shopify theme check
Common checks:
  • Liquid syntax errors
  • Performance issues
  • Accessibility problems
  • Translation key issues
VS Code Extension: If you’re using Visual Studio Code, you’ll be prompted to install the Theme Check extension when you open the project.
Horizon runs Theme Check on every commit via Shopify/theme-check-action to ensure code quality.

​
Git Configuration

Horizon includes a .gitignore file configured for theme development: 
config/settings_data.json
.shopifyignore
Important: config/settings_data.json is ignored by default because it contains store-specific settings. Each developer should maintain their own version.

​
Staying Up to Date

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

Add Upstream Remote

Add the official Horizon repository as a remote:
git remote add upstream https://github.com/Shopify/horizon.git
Verify your remotes:
git remote -v
You should see:
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)
2

Fetch Upstream Changes

Fetch the latest changes from Horizon:
git fetch upstream
3

Merge Changes

Merge the upstream changes into your branch:
git pull upstream main
This may create merge conflicts if you’ve modified the same files. Resolve conflicts carefully, testing your theme after merging.

​
Troubleshooting

​
CLI Connection Issues

Problem: Can’t connect to Shopify store 
# Clear CLI credentials and re-authenticate
shopify auth logout
shopify theme dev

​
Port Already in Use

Problem: Development server won’t start 
# Use a different port
shopify theme dev --port 9293

​
Files Not Syncing

Problem: Changes aren’t appearing in the browser
  1. Check that the file isn’t ignored in .shopifyignore
  2. Try restarting the development server
  3. Clear your browser cache
  4. Check for Liquid syntax errors in the terminal

​
Theme Check Errors

Problem: Theme Check reports issues Run Theme Check to see specific issues: 
shopify theme check
Fix reported issues or add exceptions to .theme-check.yml if needed.

​
Next Steps

Now that your development environment is set up, explore these resources:

Core Concepts

Learn about Horizon’s architecture and design patterns

Components

Explore the web components that power Horizon

Theming Guide

Customize colors, typography, and styles

API Reference

Detailed API documentation for all components

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us