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

# Getting Started

> Set up your local development environment and start building with Horizon

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

<Steps>
  <Step title="Clone the Repository">
    Clone the Horizon repository from GitHub to your local machine:

    ```bash theme={null}
    git clone https://github.com/Shopify/horizon.git
    cd horizon
    ```

    This creates a local copy of the Horizon theme in a directory called `horizon`.
  </Step>

  <Step title="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):**

    ```bash theme={null}
    brew tap shopify/shopify
    brew install shopify-cli
    ```

    **Install via npm:**

    ```bash theme={null}
    npm install -g @shopify/cli @shopify/theme
    ```

    **Install via Ruby gem:**

    ```bash theme={null}
    gem install shopify-cli
    ```

    Verify the installation:

    ```bash theme={null}
    shopify version
    ```

    <Note>
      You'll need Node.js 18+ and npm 8+ for the npm installation method.
    </Note>
  </Step>

  <Step title="Connect to a Shopify Store">
    Authenticate with Shopify and connect your theme to a development store:

    ```bash theme={null}
    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

    <Tip>
      If you don't have a development store, you can [create one for free](https://help.shopify.com/en/partners/dashboard/managing-stores/development-stores) in your Shopify Partner account.
    </Tip>
  </Step>

  <Step title="Start Developing">
    Once the development server is running, you'll see output like this:

    ```bash theme={null}
    ╭─ 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.
  </Step>
</Steps>

## 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:

```bash theme={null}
# 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.

<Warning>
  Settings changed in the theme editor must be manually pulled to your local environment using:

  ```bash theme={null}
  shopify theme pull
  ```
</Warning>

## Project Structure

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

### Core Directories

<AccordionGroup>
  <Accordion title="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"`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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' %}`.
  </Accordion>

  <Accordion title="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
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Essential Commands

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

### Development Server

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# List all themes on your store
shopify theme list

# Share a preview link
shopify theme share

# Open the theme editor
shopify theme open
```

<Tip>
  Run `shopify theme --help` to see all available commands and options.
</Tip>

## Development Tools

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

### Theme Check

[Theme Check](https://github.com/shopify/theme-check) validates and lints your Shopify themes. It's included in Horizon's VS Code configuration.

**Run Theme Check:**

```bash theme={null}
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](https://marketplace.visualstudio.com/items?itemName=Shopify.theme-check-vscode) when you open the project.

<Note>
  Horizon runs Theme Check on every commit via [Shopify/theme-check-action](https://github.com/Shopify/theme-check-action) to ensure code quality.
</Note>

### Git Configuration

Horizon includes a `.gitignore` file configured for theme development:

```gitignore theme={null}
config/settings_data.json
.shopifyignore
```

<Warning>
  **Important:** `config/settings_data.json` is ignored by default because it contains store-specific settings. Each developer should maintain their own version.
</Warning>

## Staying Up to Date

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

<Steps>
  <Step title="Add Upstream Remote">
    Add the official Horizon repository as a remote:

    ```bash theme={null}
    git remote add upstream https://github.com/Shopify/horizon.git
    ```

    Verify your remotes:

    ```bash theme={null}
    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)
    ```
  </Step>

  <Step title="Fetch Upstream Changes">
    Fetch the latest changes from Horizon:

    ```bash theme={null}
    git fetch upstream
    ```
  </Step>

  <Step title="Merge Changes">
    Merge the upstream changes into your branch:

    ```bash theme={null}
    git pull upstream main
    ```

    <Warning>
      This may create merge conflicts if you've modified the same files. Resolve conflicts carefully, testing your theme after merging.
    </Warning>
  </Step>
</Steps>

## Troubleshooting

### CLI Connection Issues

**Problem:** Can't connect to Shopify store

```bash theme={null}
# Clear CLI credentials and re-authenticate
shopify auth logout
shopify theme dev
```

### Port Already in Use

**Problem:** Development server won't start

```bash theme={null}
# 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:

```bash theme={null}
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:

<CardGroup cols={2}>
  <Card title="Core Concepts" icon="book" href="/architecture/overview">
    Learn about Horizon's architecture and design patterns
  </Card>

  <Card title="Components" icon="cube" href="/components/sections/overview">
    Explore the web components that power Horizon
  </Card>

  <Card title="Theming Guide" icon="palette" href="/customization/settings">
    Customize colors, typography, and styles
  </Card>

  <Card title="API Reference" icon="code" href="/reference/sections">
    Detailed API documentation for all components
  </Card>
</CardGroup>

## Additional Resources

* [Shopify CLI Documentation](https://shopify.dev/docs/themes/tools/cli)
* [Theme Development Best Practices](https://shopify.dev/docs/themes/best-practices)
* [Liquid Documentation](https://shopify.dev/docs/api/liquid)
* [Theme Architecture Guide](https://shopify.dev/docs/themes/architecture)