shopify-local-dev-loop

name	shopify-local-dev-loop
description	Configure Shopify local development with Shopify CLI, hot reload, and ngrok tunneling. Use when setting up a development environment, configuring test workflows, or establishing a fast iteration cycle with Shopify. Trigger with phrases like "shopify dev setup", "shopify local development", "shopify dev environment", "develop with shopify", "shopify CLI dev".
allowed-tools	Read, Write, Edit, Bash(npm:*), Bash(pnpm:*), Bash(npx:*), Bash(shopify:*), Grep
version	2.7.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","ecommerce","shopify"]
compatibility	Designed for Claude Code

Shopify Local Dev Loop

Overview

Set up a fast, reproducible local development workflow using Shopify CLI, ngrok tunneling for webhooks, and Vitest for testing against the Shopify API.

Prerequisites

• Completed shopify-install-auth setup
• Node.js 18+ with npm/pnpm
• Shopify CLI 3.x (npm install -g @shopify/cli)
• A Shopify Partner account and development store

Instructions

Step 1: Scaffold with Shopify CLI

# Create a new Remix-based Shopify app (recommended)
shopify app init

# Or scaffold manually
mkdir my-shopify-app && cd my-shopify-app
npm init -y
npm install @shopify/shopify-api @shopify/shopify-app-remix \
  @shopify/app-bridge-react @remix-run/node @remix-run/react

Step 2: Project Structure

my-shopify-app/
├── app/
│   ├── routes/
│   │   ├── app._index.tsx      # Main app page
│   │   ├── app.products.tsx    # Products management
│   │   ├── auth.$.tsx          # OAuth callback
│   │   └── webhooks.tsx        # Webhook handler
│   ├── shopify.server.ts       # Shopify API client setup
│   └── root.tsx
├── extensions/                  # Theme app extensions
├── shopify.app.toml             # App configuration
├── .env                         # Local secrets (git-ignored)
├── .env.example                 # Template for team
└── package.json

Step 3: Configure shopify.app.toml

Central app configuration with scopes, auth redirects, and mandatory GDPR webhook subscriptions.

See App TOML Config for the complete configuration file.

Step 4: Start Dev Server with Tunnel

# Shopify CLI handles ngrok tunnel + OAuth automatically
shopify app dev

# This will:
# 1. Start your app on localhost:3000
# 2. Create an ngrok tunnel
# 3. Update your app URLs in Partner Dashboard
# 4. Open your app in the dev store admin
# 5. Hot reload on file changes

Step 5: Set Up Testing

Vitest setup with mocked Shopify API client and recommended package.json scripts for the dev workflow.

See Vitest Shopify Mock for the complete test setup.