- Setting Up Shopify Theme Development with Shopify CLI on Mac: A Practical Guide for Next.js and React Devs
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.

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