Skip to content
Skills Library
Programming · Tool integration

shopify-local-dev-loop

/shopify-local-dev-loop

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

Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
6
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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

Triggers from the description

shopify dev setupshopify local developmentshopify dev environmentdevelop with shopifyshopify CLI dev
Original author 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".

How it works

  1. Overview
  2. Prerequisites
  3. Instructions
  4. Output
  5. Error Handling
  6. Examples
  7. Resources
Original SKILL.md headings · 155 lines, 626 words
SKILL.md preview
---
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

```bash
# 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](references/app-toml-config.md) for the complete configuration file.

### Step 4: Start Dev Server with Tunnel

```bash
# 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](references/vitest-shopify-mock.md) for the complete test setup.

### Step 6: GraphQL Explorer for Development

```bash
# 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

```typescript
// 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

```typescript
// 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](https://shopify.dev/docs/apps/build/cli-for-apps)
- [Shopify App Remix Template](https://github.com/Shopify/shopify-app-template-remix)
- [Vitest Documentation](https://vitest.dev/)
- [Shopify GraphiQL Explorer](https://shopify.dev/docs/apps/build/graphql)
Files in this package (3)
  • SKILL.md 5 KB
  • references/app-toml-config.md 1 KB
  • references/vitest-shopify-mock.md 1 KB

Versions

The database has no other skills named shopify-local-dev-loop.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version be8ec8659573 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100posthog-local-dev-loop
    Configure PostHog local development with hot reload and testing. Use when setting up a development environment, configuring test workflows, or establishing a fast iteration cycle with PostHog. Trigger with phrases like "posthog dev setup", "posthog local development", "posthog…
  • 100firecrawl-local-dev-loop
    Configure FireCrawl local development with hot reload and testing. Use when setting up a development environment, configuring test workflows, or establishing a fast iteration cycle with FireCrawl. Trigger with phrases like "firecrawl dev setup", "firecrawl local development",…
  • 100hex-local-dev-loop
    Configure Hex local development with hot reload and testing. Use when setting up a development environment, configuring test workflows, or establishing a fast iteration cycle with Hex. Trigger with phrases like "hex dev setup", "hex local development", "hex dev environment", "develop with hex".
  • 100framer-local-dev-loop
    Configure Framer local development with hot reload and testing. Use when setting up a development environment, configuring test workflows, or establishing a fast iteration cycle with Framer. Trigger with phrases like "framer dev setup", "framer local development", "framer dev…
  • 100shopify-setup
    Set up a Shopify development environment — Shopify CLI installation, Partner account, development stores, environment variables, project structures for themes, apps, and Hydrogen. Use when starting a new Shopify project.
  • 96shopify
    Use when the user asks to build Shopify apps, themes, or extensions.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.