Setting Up Shopify Theme Development with Shopify CLI on Mac: A Practical Guide for Next.js and React Devs

A fast, practical guide for modern frontend devs to install, update, and use Shopify CLI for theme development on macOS. Includes full command reference and best practices for smooth local work.

·Matija Žiberna·
Setting Up Shopify Theme Development with Shopify CLI on Mac: A Practical Guide for Next.js and React Devs

Shopify theme development has gotten much simpler over the years. If you have a MacBook, you can get started fast. This guide walks you through a battle-tested setup using the latest Shopify CLI, so you can develop, preview, and push themes with confidence.

If you already build with React or Next.js, the workflow will feel familiar: CLI tools, local development, and quick reloads. But Shopify’s CLI moves fast and can introduce breaking changes. Version control and regular updates matter. Below, you’ll find copy-paste commands, version checks, and gotchas learned the hard way.


Why the Shopify CLI Matters Now

It used to be confusing. Theme kit, legacy CLIs, weird login flows—this is all in the past. Today, Shopify CLI handles everything:

  • Native theme development (Liquid)
  • App development (Node or Rails)
  • Headless storefronts (Hydrogen)

You get one tool for all workflows, which makes onboarding and switching between projects much easier.


Prerequisites

  • MacBook with Homebrew for easy installs and updates
  • Node.js v18+ (Shopify CLI is Node-based)
  • Access to a Shopify partner account and a dev store

1. Install Shopify CLI with Homebrew

Shopify recommends using npm for a global install, but Homebrew is even easier to manage on Mac. The formula keeps you up to date.

brew tap shopify/shopify
brew install shopify-cli

Or, if you want the npm route (recommended if you're already using npm for other global tools):

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

Why use brew?
Homebrew makes it simple to update and switch versions. This is crucial because Shopify updates the CLI often and older versions can break quickly.


2. Always Use the Latest Version

Shopify loves to update the CLI and sometimes breaks things.
Check your installed version to avoid headaches:

shopify version

If you see output like:

@shopify/cli/3.82.0 darwin-arm64 node-v24.3.0

You're on a recent release.

Update often:
With Homebrew:

brew upgrade shopify-cli

With npm:

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

Pro tip: Check the CLI changelog when you hit weird errors.


3. Authenticate to Your Store

CLI v3+ no longer uses a simple shopify login command. You authenticate per command using the --store flag:

shopify theme pull --store your-dev-store.myshopify.com

To avoid retyping your store every command, set it as an environment variable:

export SHOPIFY_FLAG_STORE=your-dev-store.myshopify.com

Or add to a .env file in your project:

SHOPIFY_FLAG_STORE=your-dev-store.myshopify.com

4. Pull Your Theme Repo

To work on an existing theme, clone it locally:

shopify theme pull

This downloads all theme files — Liquid templates, JSON files, assets, and config.

You must run this inside your theme's folder or specify a folder to pull into.

shopify-cli-mac


5. Start the Local Dev Server

Start the live preview server with:

shopify theme dev

Features:

  • Hot reloads as you change files
  • Preview URL only you can access
  • Uploads your theme as a development copy, separate from live

6. Push Changes to Shopify

When you’re ready to update the store:

shopify theme push

To make your theme live:

shopify theme push --live

7. Switch Between Stores

No need for login or logout commands. Just use the --store flag:

shopify theme pull --store different-store.myshopify.com

Or update your environment variable.


Shopify CLI Overview and Reference

Latest versions combine tools for:

  • App development (shopify app)
  • Theme development (shopify theme)
  • Hydrogen storefronts (shopify hydrogen)

See all commands:

shopify commands

Check versions and upgrades:

shopify version
shopify upgrade

If you get stuck, run:

shopify help

And see Shopify’s docs and changelogs.


Copy-Paste Setup Summary

# Install Shopify CLI (choose one)
brew install shopify-cli
# or
npm install -g @shopify/cli @shopify/theme

# Check version
shopify version

# Authenticate and pull your theme
shopify theme pull --store your-store.myshopify.com

# Start local dev
shopify theme dev

# Push changes
shopify theme push

# Make theme live
shopify theme push --live

Full Shopify CLI Commands Reference

Below is a comprehensive list of current Shopify CLI commands (v3.82.0+). Commands cover app development, theme work, Hydrogen (headless), and more. Use shopify help or shopify commands for the latest updates and usage.

Click to expand the full command list
# Core commands
commands                       List all shopify commands.
help                           Display help for Shopify CLI.
upgrade                        Shows details on how to upgrade Shopify CLI.
version                        Shopify CLI version currently installed.
search                         Starts a search on shopify.dev.

# Config & Authentication
auth logout                    Logs you out of the Shopify account or Partner account and store.
config autocorrect off         Disable autocorrect. Off by default.
config autocorrect on          Enable autocorrect. Off by default.
config autocorrect status      Check whether autocorrect is enabled or disabled. On by default.

# App development
app build                      Build the app, including extensions.
app config link                Fetch your app configuration from the Partner Dashboard.
app config use                 Activate an app configuration.
app deploy                     Deploy your Shopify app.
app dev                        Run the app.
app dev clean                  Cleans up the app preview from the selected store.
app env pull                   Pull app and extensions environment variables.
app env show                   Display app and extensions environment variables.
app function build             Compile a function to wasm.
app function replay            Replays a function run from an app log.
app function run               Run a function locally for testing.
app function schema            Fetch the latest GraphQL schema for a function.
app function typegen           Generate GraphQL types for a JavaScript function.
app generate extension         Generate a new app Extension.
app import-extensions          Import dashboard-managed extensions into your app.
app info                       Print basic information about your app and extensions.
app init                       Create a new app project.
app logs                       Stream detailed logs for your Shopify app.
app logs sources               Print out a list of sources that may be used with the logs command.
app release                    Release an app version.
app versions list              List deployed versions of your app.
app webhook trigger            Trigger delivery of a sample webhook topic payload to a designated address.

# Theme development
theme check                    Validate the theme.
theme console                  Shopify Liquid REPL (read-eval-print loop) tool.
theme delete                   Delete remote themes from the connected store. This command can't be undone.
theme dev                      Uploads the current theme as a development theme and previews URLs.
theme info                     Displays information about your theme environment, including your current store.
theme init                     Clones a Git repository to use as a starting point for building a new theme.
theme language-server          Start a Language Server Protocol server.
theme list                     Lists the themes in your store, along with their IDs and statuses.
theme metafields pull          Download metafields definitions from your shop into a local file.
theme open                     Opens the preview of your remote theme.
theme package                  Package your theme into a .zip file, ready to upload to the Online Store.
theme profile                  Profile the Liquid rendering of a theme page.
theme publish                  Set a remote theme as the live theme.
theme pull                     Download your remote theme files locally.
theme push                     Uploads your local theme files to the connected store, overwriting the remote version if specified.
theme rename                   Renames an existing theme.
theme share                    Creates a shareable, unpublished, and new theme on your theme library with a randomized name.

# Hydrogen (headless)
hydrogen build                 Builds a Hydrogen storefront for production.
hydrogen check                 Returns diagnostic information about a Hydrogen storefront.
hydrogen codegen               Generate types for the Storefront API queries found in your project.
hydrogen customer-account-push Push project configuration to admin.
hydrogen debug cpu             Builds and profiles the server startup time of the app.
hydrogen deploy                Builds and deploys a Hydrogen storefront to Oxygen.
hydrogen dev                   Runs Hydrogen storefront in an Oxygen worker for development.
hydrogen env list              List the environments on your linked Hydrogen storefront.
hydrogen env pull              Populate your .env with variables from your Hydrogen storefront.
hydrogen env push              Push environment variables from the local .env file to your linked Hydrogen storefront.
hydrogen generate route        Generates a standard Shopify route.
hydrogen generate routes       Generates all supported standard Shopify routes.
hydrogen init                  Creates a new Hydrogen storefront.
hydrogen link                  Link a local project to one of your shop's Hydrogen storefronts.
hydrogen list                  Returns a list of Hydrogen storefronts available on a given shop.
hydrogen login                 Login to your Shopify account.
hydrogen logout                Logout of your local session.
hydrogen preview               Runs a Hydrogen storefront in an Oxygen worker for production.
hydrogen setup                 Scaffold routes and core functionality.
hydrogen setup css             Setup CSS strategies for your project.
hydrogen setup markets         Setup support for multiple markets in your project.
hydrogen setup vite            EXPERIMENTAL: Upgrades the project to use Vite.
hydrogen shortcut              Creates a global `h2` shortcut for the Hydrogen CLI.
hydrogen unlink                Unlink a local project from a Hydrogen storefront.
hydrogen upgrade               Upgrade Remix and Hydrogen npm dependencies.

# Plugins (CLI extension)
plugins add                    Installs a plugin into shopify.
plugins inspect                Displays installation properties of a plugin.
plugins install                Installs a plugin into shopify.
plugins link                   Links a plugin into the CLI for development.
plugins remove                 Removes a plugin from the CLI.
plugins reset                  Remove all user-installed and linked plugins.
plugins uninstall              Removes a plugin from the CLI.
plugins unlink                 Removes a plugin from the CLI.
plugins update                 Update installed plugins.

Best, Matija

5

Comments

Enjoyed this article?
Subscribe to my newsletter for more insights and tutorials.
Matija Žiberna
Matija Žiberna
Full-stack developer, co-founder

I'm Matija Žiberna, a self-taught full-stack developer and co-founder passionate about building products, writing clean code, and figuring out how to turn ideas into businesses. I write about web development with Next.js, lessons from entrepreneurship, and the journey of learning by doing. My goal is to provide value through code—whether it's through tools, content, or real-world software.

You might be interested in