---

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 jeremy@intentsolutions.io 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.

Step 6: GraphQL Explorer for Development

# Open the Shopify GraphiQL explorer for your store
# Navigate to: https://your-store.myshopify.com/admin/api/2025-04/graphql.json
# Use the Shopify Admin GraphiQL app (install from admin)

# Or use curl to test queries directly:
curl -X POST \
  "https://your-store.myshopify.com/admin/api/${SHOPIFY_API_VERSION:-2025-04}/graphql.json" \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Access-Token: shpat_xxx" \
  -d '{"query": "{ shop { name } }"}'

Output

• Shopify CLI dev server running with hot reload
• Ngrok tunnel forwarding to localhost
• Test suite with mocked Shopify API calls
• GraphQL explorer available for API exploration

Error Handling

Error	Cause	Solution
Could not find a Shopify partner organization	CLI not logged in	Run shopify auth login
Port 3000 already in use	Another process on port	Kill process or use --port 3001
Tunnel connection failed	ngrok issues	Check ngrok status or use --tunnel-url
App not installed on store	First time setup	Open the URL CLI provides, accept install
SHOPIFY_API_KEY not set	Missing .env	Copy from .env.example and fill in values

Examples

Debug with Request Logging

// Enable verbose request logging in development
import { LogSeverity } from "@shopify/shopify-api";

const shopify = shopifyApi({
  // ... other config
  logger: {
    level: LogSeverity.Debug, // Logs all requests/responses
    httpRequests: true,
    timestamps: true,
  },
});

Seed Test Data

// scripts/seed-dev-store.ts — create test products
async function seedStore(client: any) {
  const products = [
    { title: "Test Widget", productType: "Widget", vendor: "Dev" },
    { title: "Test Gadget", productType: "Gadget", vendor: "Dev" },
  ];

  for (const product of products) {
    await client.request(`
      mutation { productCreate(product: {
        title: "${product.title}",
        productType: "${product.productType}",
        vendor: "${product.vendor}"
      }) {
        product { id title }
        userErrors { field message }
      }}
    `);
  }
}

Resources

• Shopify CLI Documentation
• Shopify App Remix Template
• Vitest Documentation
• Shopify GraphiQL Explorer