Local Development with Shopify CLI

While Shopify’s online code editor works great for quick changes, professional theme development calls for a more powerful setup. The Shopify CLI lets you develop themes locally using your favorite code editor, with hot reloading, version control, and all the tools you’re used to.

Why Develop Locally?

The browser-based editor is convenient, but local development offers significant advantages:

Your favorite editor: Use VS Code, Sublime, Vim, or any editor you prefer
Version control: Track changes with Git, collaborate with others, roll back mistakes
Hot reloading: See changes instantly without manual refreshing
Faster workflow: No waiting for browser round-trips
Better tooling: Linters, formatters, snippets, and extensions
Offline capability: Work on your theme without an internet connection

Prerequisites

Before installing the Shopify CLI, you’ll need:

Node.js

The Shopify CLI requires Node.js version 18 or higher.

Check if you have it:

node --version

Install Node.js:

macOS/Linux: Use nvm (Node Version Manager)
Windows: Download from nodejs.org
Homebrew (macOS): brew install node

A Shopify Partners Account and Dev Store

You’ll need somewhere to run your theme. If you haven’t already, follow the previous lesson on Setting Up Your Shopify Development Environment.

Installing the Shopify CLI

The Shopify CLI is a command-line tool that handles authentication, theme syncing, and local development.

Installation via npm (Recommended)

npm install -g @shopify/cli @shopify/theme

Installation via Homebrew (macOS)

brew tap shopify/shopify
brew install shopify-cli

Verify Installation

Check that everything installed correctly:

shopify version

You should see output like @shopify/cli/3.x.x.

Authentication

Before you can work with themes, you need to authenticate with your Shopify account.

Logging In

shopify auth login

This opens a browser window where you’ll:

Log in to your Shopify Partners account
Authorize the CLI to access your stores
Return to the terminal

The CLI stores your credentials securely, so you won’t need to log in again (unless your session expires).

Switching Accounts

If you work with multiple Partners accounts:

shopify auth logout
shopify auth login

Creating a New Theme

To start a new theme from scratch:

shopify theme init my-theme

This creates a new directory with a basic theme structure. You’ll be prompted to choose a starting point:

Dawn: Shopify’s reference theme (recommended for learning)
Skeleton: A minimal theme with just the essentials

Project Structure

After initialization, you’ll have:

my-theme/
├── assets/
├── config/
│   ├── settings_data.json
│   └── settings_schema.json
├── layout/
│   └── theme.liquid
├── locales/
├── sections/
├── snippets/
└── templates/
    ├── 404.json
    ├── article.json
    ├── blog.json
    ├── cart.json
    ├── collection.json
    ├── index.json
    ├── list-collections.json
    ├── page.json
    ├── product.json
    └── search.json

Pulling an Existing Theme

To work on a theme that’s already on your store:

shopify theme pull

The CLI will prompt you to:

Select a store (if you have access to multiple)
Choose which theme to download

The theme files are downloaded to your current directory.

Pulling to a Specific Directory

shopify theme pull --path ./my-existing-theme

Pulling a Specific Theme by ID

If you know the theme ID:

shopify theme pull --theme 123456789

You can find theme IDs in your store admin under Online Store → Themes (look at the URL when viewing a theme).

Local Development Server

This is where the magic happens. The development server syncs your local files with Shopify and provides hot reloading.

Starting the Dev Server

Navigate to your theme directory and run:

shopify theme dev

The first time you run this, you’ll be prompted to select a store. The CLI then:

Creates a development theme on your store
Syncs your local files to it
Starts a local server (usually at http://127.0.0.1:9292)
Opens a preview in your browser

What You’ll See

╭─ success ────────────────────────────────────────────────────────────────────╮
│                                                                              │
│  Development theme: #123456789 (Development)                                 │
│                                                                              │
│  Preview your theme:                                                         │
│  • http://127.0.0.1:9292                                                     │
│                                                                              │
│  Customize your theme in the Theme Editor:                                   │
│  • https://your-store.myshopify.com/admin/themes/123456789/editor            │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

Hot Reloading

Now the workflow is seamless:

Edit a file in your code editor
Save the file
The browser automatically refreshes with your changes

No manual syncing, no page refreshing. Just instant feedback.

Connecting to Your Store’s Data

The development server uses your actual store data:

Products, collections, and pages
Customer accounts (in preview mode)
Theme settings

This means you can test your Liquid code against real data, not just placeholders.

Dev Server Options

Useful flags for the dev server:

# Use a specific store
shopify theme dev --store your-store.myshopify.com

# Disable automatic browser opening
shopify theme dev --open=false

# Specify a port
shopify theme dev --port 3000

# Only sync specific paths (faster for large themes)
shopify theme dev --only "sections/*" --only "snippets/*"

Pushing Changes

When you’re ready to deploy your theme changes to your store, you have several options.

Push to Development Theme

To push all changes to your development theme:

shopify theme push

Push to a Specific Theme

To push to a particular theme (e.g., your published theme):

shopify theme push --theme 123456789

Push and Publish

To push and immediately make the theme live:

shopify theme push --publish

Warning: Be careful with --publish on production stores!

Selective Pushing

Only push specific files:

shopify theme push --only "sections/header.liquid"
shopify theme push --only "assets/*"

Ignore certain files:

shopify theme push --ignore "config/settings_data.json"

Development vs Production Themes

Understanding theme states is important for a safe workflow:

Development Theme

Created automatically by shopify theme dev. Features:

Hidden from customers
Automatically deleted after 3 days of inactivity
Perfect for active development

Unpublished Theme

A saved theme that’s not live:

Persists indefinitely
Can be previewed with a special URL
Good for staging and review

Published Theme

The live theme customers see:

Only one theme can be published at a time
Be careful when pushing directly to this!

Preview Themes

To create a shareable preview:

shopify theme push --unpublished

This creates a new unpublished theme you can share for review.

Workflow Tips

Git Integration

Initialize Git in your theme directory:

cd my-theme
git init
git add .
git commit -m "Initial theme setup"

Add a .gitignore file:

# Ignore local settings
config/settings_data.json

# Ignore OS files
.DS_Store
Thumbs.db

# Ignore editor directories
.vscode/
.idea/

Note: You might want to track settings_data.json if you need consistent settings across environments.

Editor Setup: VS Code

For the best Liquid editing experience in VS Code:

Recommended Extensions:

Shopify Liquid - Syntax highlighting and snippets
Liquid Languages Support - Additional language features
Prettier - Code formatting (with Liquid plugin)

Install from terminal:

code --install-extension Shopify.theme-check-vscode

Theme Check

Shopify’s linter for themes. The CLI includes it:

shopify theme check

This catches:

Liquid syntax errors
Performance issues
Accessibility problems
Deprecated features

Run it before pushing to production!

Multiple Themes in Development

Working on multiple themes? Use different directories:

# Clone different themes to different folders
cd ~/shopify-themes
shopify theme pull --path ./client-a-theme
shopify theme pull --path ./client-b-theme

Ignoring Files During Development

Create a .shopifyignore file in your theme root:

# Don't sync these files
config/settings_data.json
*.backup
temp/*

This prevents accidental overwrites of store-specific settings.

Common Commands Reference

Command	Description
`shopify theme dev`	Start development server
`shopify theme push`	Push theme to store
`shopify theme pull`	Download theme from store
`shopify theme init`	Create new theme
`shopify theme check`	Lint your theme
`shopify theme list`	List themes on store
`shopify theme delete`	Delete a theme
`shopify auth login`	Authenticate with Shopify
`shopify auth logout`	Log out

Troubleshooting

”Not authenticated” Error

shopify auth logout
shopify auth login

Theme Not Syncing

Make sure you’re in the theme directory:

pwd  # Should show your theme folder
ls   # Should show layout/, sections/, etc.

Port Already in Use

shopify theme dev --port 3001

Slow Syncing

Use --only to limit what’s watched:

shopify theme dev --only "sections/*" --only "snippets/*" --only "layout/*"

What’s Next?

You’re now set up for professional Shopify theme development. Here’s where to go from here:

Build a sandbox theme: Create a minimal theme for experimenting with Liquid
Continue learning: Follow the next lessons to master Liquid syntax
Explore the docs: Check out Shopify’s CLI documentation for more advanced features

With local development, you have the power of a professional development environment. Happy coding!