Development Setup

Configure your complete Shopify theme development environment on Windows with WSL. By the end of this chapter you'll have every tool installed, a development store ready, and the Dawn theme running locally with hot-reload.

📌 Chapter Overview

Time estimate: 45 – 90 minutes (first time)
Tags: CLI WSL

Architecture of Your Dev Environment

Before installing anything, understand how the pieces connect. Your development workflow looks like this:

Workflow Diagram

┌──────────────────────────────────────────────────────────┐
│  YOUR MACHINE  (Windows + WSL Ubuntu)                    │
│                                                          │
│  VS Code  ──→  Edit Liquid / CSS / JS files              │
│     │                                                    │
│     ▼                                                    │
│  Shopify CLI  ──→  shopify theme dev                     │
│     │               (local dev server on port 9292)      │
│     │                                                    │
│     ▼                                                    │
│  Browser  ──→  http://127.0.0.1:9292                     │
│               (live preview with hot reload)             │
│                                                          │
│  Git  ──→  Track changes ──→  Push to GitHub             │
│                                                          │
└──────────┬───────────────────────────────────────────────┘
           │  Shopify CLI syncs files over the network
           ▼
┌──────────────────────────────────────────────────────────┐
│  SHOPIFY CLOUD                                           │
│                                                          │
│  Development Store  ──→  Renders your theme live         │
│  (your-store.myshopify.com)                              │
│                                                          │
└──────────────────────────────────────────────────────────┘

Shopify CLI creates a secure tunnel between your local files and a real Shopify development store. When you edit a file and save, the change is pushed to Shopify's servers and the browser refreshes automatically. This gives you the speed of local development with the accuracy of a real Shopify environment.

Step 1 — Ensure WSL Is Ready

You mentioned you already have WSL installed. Let's verify it's properly configured. Open PowerShell as Administrator and run:

PowerShell (Admin)

wsl --list --verbose

You should see output like:

Output

  NAME      STATE           VERSION
* Ubuntu    Running         2

Make sure the VERSION column shows 2. WSL 2 is significantly faster than WSL 1. If you see version 1, upgrade:

PowerShell (Admin)

wsl --set-version Ubuntu 2

Now open your WSL Ubuntu terminal. All subsequent commands run inside WSL.

💡 Pro Tip

In VS Code, install the "WSL" extension by Microsoft. Then open your project with code . from the WSL terminal. VS Code connects directly to the Linux filesystem — giving you native performance instead of the slower cross-filesystem access.

Step 2 — Install Node.js via NVM

Shopify CLI requires Node.js. We'll use NVM (Node Version Manager) so you can easily switch Node versions if needed.

Install NVM

WSL Terminal

# Download and install NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Reload your shell configuration
source ~/.bashrc

# Verify NVM is installed
nvm --version

You should see a version number like 0.39.7.

Install Node.js LTS

WSL Terminal

# Install the latest LTS version
nvm install --lts

# Verify Node and npm
node --version
npm --version

You should see Node.js v18+ or v20+ (LTS). Shopify CLI requires Node.js 18 or higher.

⚠️ Common Pitfall

Don't install Node.js using sudo apt install nodejs. The Ubuntu repository often has outdated versions. Always use NVM for Node.js management — it avoids permission issues and makes upgrades seamless.

Step 3 — Install Shopify CLI

Shopify CLI is the official command-line interface for Shopify development. It handles theme previewing, file syncing, and deployment.

WSL Terminal

# Install Shopify CLI globally via npm
npm install -g @shopify/cli @shopify/theme

# Verify the installation
shopify version

You should see the version number (e.g., 3.x.x). If you get permission errors, it's because you installed Node.js without NVM — go back and use NVM.

Essential Shopify CLI Commands

Here are the commands you'll use daily:

Command	What It Does	When to Use
`shopify theme dev`	Starts a local development server with hot reload. Creates a secure tunnel to your development store.	Every time you work on a theme
`shopify theme push`	Uploads your local theme files to the Shopify store, creating or updating a theme.	Deploying changes to the store
`shopify theme pull`	Downloads the current theme files from a Shopify store to your local machine.	Getting existing theme code, or syncing changes made in the theme editor
`shopify theme info`	Shows information about the current theme and connected store.	Verifying your connection
`shopify theme list`	Lists all themes on the connected store.	Checking which themes exist on the store
`shopify auth logout`	Logs out of the current Shopify account.	Switching between stores or accounts

💡 Pro Tip

Run shopify theme dev --help to see all available flags. The most useful ones are --store (specify which store to connect to) and --theme (specify which theme to preview).

Step 4 — Create a Shopify Partner Account

A Shopify Partner account is free and gives you access to create unlimited development stores for testing.

Go to Shopify Partners

Visit partners.shopify.com and click "Join now".

Fill Out Registration

Provide your name, email, and basic business info. You can select "I'm a developer building themes" as your reason for joining.

Access the Dashboard

Once registered, you'll land on the Partner Dashboard. This is your command center for managing stores, themes, and apps.

Step 5 — Create a Development Store

Development stores are free Shopify stores specifically for building and testing themes. They have all the features of a real store but don't require a paid plan.

Navigate to Stores

In your Partner Dashboard, click "Stores" in the left sidebar, then click "Add store".

Select Store Type

Choose "Development store". Select the purpose: "Create a store to test and build".

Configure the Store

Give your store a name (e.g., gamal-theme-dev). The URL will be gamal-theme-dev.myshopify.com. Set a password and choose your country.

Add Sample Products

Once the store is created, add some sample products. You need real product data to test your theme properly. Add at least:

5–10 products with images, descriptions, and prices
2–3 collections (e.g., "New Arrivals", "Best Sellers", "Sale")
Different product variants (sizes, colors)
Products at different price points

✅ Best Practice

Use realistic product data. Don't use "Test Product 1" with no images. Use real product photos from sites like Unsplash or Burst by Shopify (Shopify's free stock photo library). Realistic data helps you see how your theme actually looks and behaves.

Step 6 — Clone and Set Up the Dawn Theme

Now let's get the Dawn theme onto your local machine and connect it to your development store.

Create Your Project Directory

WSL Terminal

# Create a directory for all your Shopify projects
mkdir -p ~/shopify-projects
cd ~/shopify-projects

Option A — Clone Dawn from GitHub

WSL Terminal

# Clone the Dawn theme repository
git clone https://github.com/Shopify/dawn.git my-first-theme

# Enter the project directory
cd my-first-theme

# Remove the original Git history (start fresh)
rm -rf .git

# Initialize your own Git repository
git init
git add .
git commit -m "Initial commit: Dawn theme base"

Option B — Use Shopify CLI to Create a Theme

WSL Terminal

# Create a new theme project (will clone Dawn automatically)
shopify theme init my-first-theme

# Enter the project directory
cd my-first-theme

Both options give you the same result: a complete Dawn theme on your local machine. Option A gives you more control over the Git history. Option B is faster.

💡 My Recommendation

Use Option A for your learning projects. Removing the original Git history and starting fresh helps you track your own changes clearly. When you push to GitHub, your commit history will show your modifications, not Shopify's entire Dawn development history.

Step 7 — Start Your First Dev Server

This is the moment of truth. Let's connect your local theme to the development store and see it live in your browser.

WSL Terminal

# Make sure you're in the theme directory
cd ~/shopify-projects/my-first-theme

# Start the development server
shopify theme dev --store gamal-theme-dev.myshopify.com

The first time you run this, Shopify CLI will:

Open your browser for authentication — log in with your Partner account
Create a development theme on your store
Upload your local files to that development theme
Start a local server (usually at http://127.0.0.1:9292)
Begin watching for file changes

You'll see output like this:

Terminal Output

╭─ info ──────────────────────────────────────────────────╮
│                                                         │
│  Your theme was created successfully!                   │
│                                                         │
│  Preview your theme:                                    │
│    • http://127.0.0.1:9292                              │
│                                                         │
│  Customize this theme in the Theme Editor:              │
│    • https://gamal-theme-dev.myshopify.com/admin/       │
│      themes/XXXXXXXXX/editor                            │
│                                                         │
│  Share your theme preview:                              │
│    • https://gamal-theme-dev.myshopify.com/             │
│      ?preview_theme_id=XXXXXXXXX                        │
│                                                         │
╰─────────────────────────────────────────────────────────╯

Watching for file changes in the theme directory...

14:23:01 Synced: sections/header.liquid
14:23:01 Synced: layout/theme.liquid

Open http://127.0.0.1:9292 in your browser. You should see your development store rendered with the Dawn theme. 🎉

Understanding Hot Reload

Now try editing a file. Open sections/header.liquid in VS Code and add a comment at the top:

sections/header.liquid

{% comment %}
  Gamal is learning Shopify theme development!
{% endcomment %}

{%- comment -%}
  The rest of the original header code below...
{%- endcomment -%}

Save the file. Look at your terminal — you'll see a sync message. Your browser will automatically refresh. This is hot reload in action.

⚠️ Important

The dev server uses a development theme, not the live theme. Your changes won't affect the published store until you explicitly run shopify theme push. This makes it completely safe to experiment.

Step 8 — Configure VS Code

Let's optimize VS Code for Shopify development.

Essential Extensions

Extension	Purpose	Publisher
Shopify Liquid	Syntax highlighting, autocomplete, formatting for Liquid files	Shopify
WSL	Connect VS Code to your WSL filesystem	Microsoft
GitLens	Enhanced Git integration — blame, history, comparisons	GitKraken
Prettier	Code formatter for CSS, JS, JSON (configure to skip .liquid files)	Prettier
Auto Rename Tag	Automatically renames paired HTML tags	Jun Han
Color Highlight	Visualizes color codes inline in CSS	naumovs

Recommended VS Code Settings

Add these to your settings.json:

.vscode/settings.json

{
  "files.associations": {
    "*.liquid": "liquid"
  },
  "editor.formatOnSave": true,
  "editor.tabSize": 2,
  "editor.wordWrap": "on",
  "editor.minimap.enabled": false,
  "editor.bracketPairColorization.enabled": true,
  "editor.guides.bracketPairs": true,
  "emmet.includeLanguages": {
    "liquid": "html"
  },
  "[liquid]": {
    "editor.defaultFormatter": null,
    "editor.formatOnSave": false
  },
  "files.exclude": {
    "**/.git": false
  }
}

💡 Emmet in Liquid Files

The emmet.includeLanguages setting is crucial. It lets you use Emmet shortcuts (like typing div.container>h2+p and pressing Tab) inside .liquid files. This dramatically speeds up your HTML writing.

Opening Your Project

WSL Terminal

# Navigate to your project
cd ~/shopify-projects/my-first-theme

# Open in VS Code (connected to WSL)
code .

VS Code will open and show "WSL: Ubuntu" in the bottom-left corner. This confirms it's connected directly to your Linux filesystem.

Step 9 — Set Up Git Workflow

Version control is non-negotiable for professional development. Here's how to set up a proper Git workflow for your Shopify themes.

Configure Git Identity

WSL Terminal

# Set your identity (used in commit messages)
git config --global user.name "Gamal"
git config --global user.email "your-email@example.com"

# Set default branch name
git config --global init.defaultBranch main

# Enable colored output
git config --global color.ui auto

Create a GitHub Repository

Create a New Repository on GitHub

Go to github.com/new. Name it my-first-shopify-theme. Set it to Private. Don't initialize with a README (we already have local files).

Connect Your Local Repo

WSL Terminal

# Add the remote origin
git remote add origin git@github.com:YOUR-USERNAME/my-first-shopify-theme.git

# Push your initial commit
git push -u origin main

⚠️ Always Use Private Repos for Learning Projects

When you're studying themes or experimenting with ideas inspired by premium themes, always use private repositories. This protects you legally and respects the intellectual property of theme creators. Only make repositories public when the code is entirely your own original work.

Create a .gitignore

Some files should never be committed to Git:

.gitignore

# OS files
.DS_Store
Thumbs.db

# Editor files
.vscode/
*.swp
*.swo

# Node modules (if using build tools)
node_modules/

# Shopify CLI
.shopify/

# Environment files
.env
.env.local

Daily Git Workflow

Here's the workflow you should follow every day you work on your theme:

WSL Terminal

# Start your work session
cd ~/shopify-projects/my-first-theme

# Check current status
git status

# Start the dev server
shopify theme dev --store gamal-theme-dev.myshopify.com

# ... make your changes ...

# Stage and commit specific changes
git add sections/my-new-section.liquid
git commit -m "feat: add hero banner section with image and CTA"

# Or stage all changes
git add .
git commit -m "refactor: update product card styling"

# Push to GitHub
git push

Writing Good Commit Messages

Professional developers write clear, descriptive commit messages. Use this pattern:

Prefix	Usage	Example
`feat:`	New feature or section	`feat: add featured collection section`
`fix:`	Bug fix	`fix: resolve mobile menu z-index issue`
`style:`	CSS/design changes	`style: update product card hover effect`
`refactor:`	Code improvement without feature change	`refactor: simplify header section logic`
`docs:`	Documentation updates	`docs: add schema descriptions`
`perf:`	Performance improvement	`perf: lazy-load below-fold images`

✅ Best Practice

Commit frequently with small, focused changes. One commit per feature or fix. This makes it easy to review changes, revert if needed, and understand your project history. Never make "mega commits" that change 50 files at once.

Step 10 — Git Branching Strategy

Use branches to experiment without risking your working code:

WSL Terminal

# Create a new branch for a feature
git checkout -b feature/hero-banner

# ... work on the hero banner ...

# Commit your work
git add .
git commit -m "feat: add hero banner section"

# Switch back to main
git checkout main

# Merge the feature branch when it's ready
git merge feature/hero-banner

# Push everything
git push

# Delete the feature branch (optional)
git branch -d feature/hero-banner

My recommended branching model for learning:

main — Your stable, working theme
feature/* — New sections or features (e.g., feature/mega-menu)
experiment/* — Design experiments you may or may not keep (e.g., experiment/dark-mode)
fix/* — Bug fixes (e.g., fix/mobile-nav)

Complete Workflow Summary

Here's your complete daily workflow in one place:

Complete Daily Workflow

# 1. Open your project
cd ~/shopify-projects/my-first-theme
code .

# 2. Create a feature branch
git checkout -b feature/new-section

# 3. Start the dev server (in a separate terminal tab)
shopify theme dev --store gamal-theme-dev.myshopify.com

# 4. Open browser to http://127.0.0.1:9292

# 5. Edit files in VS Code — changes reflect instantly

# 6. Commit when a unit of work is complete
git add .
git commit -m "feat: add announcement bar section"

# 7. Merge back to main when feature is complete
git checkout main
git merge feature/new-section
git push

# 8. When you're done for the day — stop the dev server
# Press Ctrl+C in the terminal running shopify theme dev

# 9. (Optional) Deploy to the store
shopify theme push --store gamal-theme-dev.myshopify.com

Understanding Push and Pull

Two commands that can cause confusion if misunderstood:

`shopify theme push`

This command uploads your local theme to the Shopify store. Use it when you want to deploy your changes.

WSL Terminal

# Push to a new unpublished theme
shopify theme push --unpublished --store gamal-theme-dev.myshopify.com

# Push to a specific existing theme
shopify theme push --theme THEME_ID --store gamal-theme-dev.myshopify.com

# Push and overwrite (be careful!)
shopify theme push --allow-live --store gamal-theme-dev.myshopify.com

`shopify theme pull`

This command downloads theme files from Shopify to your local machine. Use it when the merchant (or you) made changes through the theme editor and you want to sync those changes locally.

WSL Terminal

# Pull the live theme
shopify theme pull --store gamal-theme-dev.myshopify.com

# Pull a specific theme
shopify theme pull --theme THEME_ID --store gamal-theme-dev.myshopify.com

🚨 Critical Warning

shopify theme pull will overwrite your local files. Always commit your local changes to Git before pulling. This way you can always recover your work if something goes wrong.

Troubleshooting Common Issues

Problem	Cause	Solution
`shopify: command not found`	Shopify CLI not installed or not in PATH	Run `npm install -g @shopify/cli @shopify/theme` again
Authentication loop — browser keeps opening	Session expired or browser cookie issue	Run `shopify auth logout` then try again
`EACCES` permission error with npm	Node.js installed without NVM (using sudo)	Uninstall Node, install NVM, then reinstall Node via NVM
Port 9292 already in use	Another dev server is running	Kill the existing process or use `--port 9293`
Files not syncing	File watcher limit reached	Increase inotify limit: `echo fs.inotify.max_user_watches=524288 \| sudo tee -a /etc/sysctl.conf && sudo sysctl -p`
Slow file system in WSL	Working on Windows filesystem (`/mnt/c/`)	Move project to Linux filesystem (`~/`). Always work in `~`, not `/mnt/c/`

💡 Pro Tip — WSL Performance

This is critical: always keep your project files inside the Linux filesystem (~/shopify-projects/), not in /mnt/c/Users/.... Accessing Windows files from WSL is slow due to filesystem translation. Keeping files in ~/ gives you native Linux speed.

Verification Checklist

Before moving to the next chapter, verify everything is working:

WSL 2 is running Ubuntu
Node.js is installed via NVM (v18+)
shopify version shows the CLI version
You have a Shopify Partner account
You have a development store with sample products
Dawn theme is cloned locally
shopify theme dev starts successfully
You can see the theme at http://127.0.0.1:9292
VS Code opens with WSL connection
Shopify Liquid extension is installed
Git is configured with your identity
Private GitHub repository is created and connected
You've made at least one test commit and push

🎉 Congratulations!

You now have a professional Shopify theme development environment. This same setup is used by developers at agencies and freelancers building premium themes. In the next chapter, we'll explore how Shopify's architecture works under the hood.

← Previous Introduction Next Chapter → Shopify Architecture