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

# Development Workflow

> Best practices and workflow for developing with the Horizon theme

This guide covers the recommended development workflow and best practices for working with Horizon.

## Development Philosophy

Horizon follows these core principles:

<CardGroup cols={2}>
  <Card title="Web-Native" icon="globe">
    Leverage the latest web browsers to their fullest, while maintaining support for older ones through progressive enhancement—not polyfills.
  </Card>

  <Card title="Lean and Fast" icon="bolt">
    Functionality and design defaults to "no" until it meets quality requirements. Code ships on quality.
  </Card>

  <Card title="Server-Rendered" icon="server">
    HTML must be rendered by Shopify servers using Liquid. Business logic and platform primitives belong on the server.
  </Card>

  <Card title="Functional, Not Pixel-Perfect" icon="mobile">
    Use semantic markup, progressive enhancement, and clever design to ensure themes remain functional regardless of browser.
  </Card>
</CardGroup>

## Daily Development Workflow

<Steps>
  <Step title="Start the development server">
    Begin each session by starting the local development server:

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

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

  <Step title="Test in the browser">
    Preview changes in real-time using the local preview URL or the theme editor preview link.
  </Step>

  <Step title="Validate your code">
    Run Theme Check to catch issues:

    ```bash theme={null}
    shopify theme check
    ```
  </Step>

  <Step title="Commit your changes">
    Commit working changes to version control:

    ```bash theme={null}
    git add .
    git commit -m "Add product quick view feature"
    ```
  </Step>
</Steps>

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

<Steps>
  <Step title="Navigate to your theme folder">
    ```bash theme={null}
    cd your-theme-directory
    ```
  </Step>

  <Step title="Verify your remotes">
    Check that you have both `origin` and `upstream` remotes:

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

  <Step title="Add upstream remote (if needed)">
    If you don't see an `upstream` remote, add one:

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

  <Step title="Pull latest changes">
    Fetch and merge the latest Horizon changes:

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

    Resolve any merge conflicts if they occur.
  </Step>
</Steps>

<Warning>
  Pulling upstream changes may introduce breaking changes. Always test thoroughly after merging.
</Warning>

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

```bash theme={null}
# Run Theme Check for Liquid validation
shopify theme check

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

## Deployment Workflow

<Steps>
  <Step title="Final validation">
    Run a complete theme check:

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

    Ensure all issues are resolved before deploying.
  </Step>

  <Step title="Push to a new theme">
    Upload your theme to the store without making it live:

    ```bash theme={null}
    shopify theme push --unpublished
    ```

    This creates a new theme you can preview and test.
  </Step>

  <Step title="Test the uploaded theme">
    Test the theme thoroughly on your store before publishing.
  </Step>

  <Step title="Publish the theme">
    When ready, publish from the Shopify admin or use:

    ```bash theme={null}
    shopify theme publish
    ```
  </Step>
</Steps>

## 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](https://shopify.dev/docs/storefronts/themes/tools/theme-check)
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

<CardGroup cols={2}>
  <Card title="Shopify CLI Reference" icon="terminal" href="/development/shopify-cli">
    Complete guide to Shopify CLI commands
  </Card>

  <Card title="Theme Check" icon="check" href="/development/theme-check">
    Learn about validation and linting
  </Card>

  <Card title="Customization" icon="palette" href="/customization/settings">
    Customize Horizon for your needs
  </Card>

  <Card title="Contributing" icon="code-branch" href="/resources/contributing">
    Learn about contributing to Horizon
  </Card>
</CardGroup>