Getting Started

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.

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.

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.

Connect to a Shopify Store

Authenticate with Shopify and connect your theme to a development store:

shopify theme dev

This command will:

Prompt you to log in to your Shopify Partner account
Let you select or create a development store
Upload your theme to the store
Start a local development server

If you don’t have a development store, you can create one for free in your Shopify Partner account.

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

assets/ - JavaScript, CSS, and Media

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".

sections/ - Page Sections

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.

blocks/ - Reusable Theme Blocks

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.

snippets/ - Liquid Snippets

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' %}.

templates/ - Page Templates

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

config/ - Theme Settings

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:

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)

Fetch Upstream Changes

Fetch the latest changes from Horizon:

git fetch upstream

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

Check that the file isn’t ignored in .shopifyignore
Try restarting the development server
Clear your browser cache
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

Overview

Core Concepts

Development

Customization

Features

Getting Started

Quick Start

Development Workflow

File Watching & Hot Reload

Theme Editor

Project Structure

Core Directories

Essential Commands

Development Server

Theme Management

Theme Information

Development Tools

Theme Check

Git Configuration

Staying Up to Date

Troubleshooting

CLI Connection Issues

Port Already in Use

Files Not Syncing

Theme Check Errors

Next Steps

Core Concepts

Components

Theming Guide

API Reference

Additional Resources

​Quick Start

​Development Workflow

​File Watching & Hot Reload

​Theme Editor

​Project Structure

​Core Directories

​Essential Commands

​Development Server

​Theme Management

​Theme Information

​Development Tools

​Theme Check

​Git Configuration

​Staying Up to Date

​Troubleshooting

​CLI Connection Issues

​Port Already in Use

​Files Not Syncing

​Theme Check Errors

​Next Steps

Core Concepts

Components

Theming Guide

API Reference

​Additional Resources

Quick Start

Development Workflow

File Watching & Hot Reload

Theme Editor

Project Structure

Core Directories

Essential Commands

Development Server

Theme Management

Theme Information

Development Tools

Theme Check

Git Configuration

Staying Up to Date

Troubleshooting

CLI Connection Issues

Port Already in Use

Files Not Syncing

Theme Check Errors

Next Steps

Additional Resources