Shopify Development Workflows with Claude Code
This section covers the hands-on workflows that make Claude Code indispensable for Shopify development. Each workflow is a pattern you will use repeatedly -- from scaffolding new apps to debugging production webhook failures at 2 AM.
Scaffolding Apps with Natural Language
The traditional way to start a Shopify app involves navigating documentation, choosing templates, and manually configuring boilerplate. With Claude Code, you describe what you want in plain English.
Starting a New Remix App
> Create a new Shopify Remix app for managing product bundles.
It should have:
- A page listing all products with bundle tagging
- A bundle creation form using Polaris
- GraphQL queries for product listing and metafield management
- A webhook handler for orders containing bundles
- Prisma schema for storing bundle configurations
Claude Code will generate the complete file structure, write each file, set up the Prisma schema, create GraphQL query files, and wire everything together. It knows the Shopify Remix app template conventions and follows them.
For best results, scaffold the base app with Shopify CLI first, then use Claude Code to build features on top:
shopify app init --template remix
cd my-app
claude
This gives Claude Code a proper foundation with authentication, session handling, and App Bridge already configured.
Scaffolding App Extensions
App extensions (theme extensions, checkout UI extensions, admin UI extensions) have specific file structure requirements. Claude Code handles these natively:
> Create a checkout UI extension that displays a loyalty points
summary. It should show the customer's current points balance
and how many points they'll earn from this purchase. Use the
Checkout UI extensions API with React.
Claude Code generates the shopify.extension.toml configuration, the React component using checkout UI components (Banner, Text, BlockStack), and any necessary utility functions.
Generating GraphQL Queries
Shopify's Admin API is GraphQL-first, and writing correct queries is one of the most common tasks. Claude Code excels here because it understands the Shopify GraphQL schema deeply.
Product Queries
> Write a GraphQL query to fetch products with their variants,
prices, inventory levels, and metafields. Include cursor-based
pagination. Use the 2025-01 API version.
Claude Code produces:
export const PRODUCTS_QUERY = `#graphql
query GetProducts($first: Int!, $after: String) {
products(first: $first, after: $after) {
edges {
cursor
node {
id
title
status
totalInventory
variants(first: 10) {
edges {
node {
id
title
price
inventoryQuantity
selectedOptions {
name
value
}
}
}
}
metafields(first: 5) {
edges {
node {
namespace
key
value
type
}
}
}
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
`;
Mutation Generation
> Write a GraphQL mutation to update product metafields in bulk,
including the TypeScript types for the variables and response.
- Forgetting
userErrors: Claude Code always includesuserErrors { field, message }in mutation responses - Wrong ID format: It uses the correct
gid://shopify/Product/123format - Missing pagination: It defaults to cursor-based pagination instead of fetching unbounded lists
- API version mismatch: When your CLAUDE.md specifies an API version, it respects that version's schema
Theme Development with Claude Code
Theme development involves Liquid templates, JSON schemas, CSS, and JavaScript all working together. Claude Code can navigate this multi-language environment seamlessly.
Creating Custom Sections
> Create a Liquid section called "featured-collection-tabs" that
displays products from multiple collections in a tabbed interface.
Include the section schema with settings for:
- Up to 5 collection pickers
- Tab style (underline, pill, boxed)
- Products per tab (4, 8, 12)
- Mobile layout option (scroll, stack)
Make it accessible and performant.
Claude Code generates the complete section: Liquid template with proper {% schema %} block, CSS with responsive design, vanilla JavaScript for tab functionality, and semantic HTML with ARIA attributes.
Theme Blocks and App Blocks
> Create a theme app extension block that displays real-time
inventory status on product pages. It should show "In Stock",
"Low Stock" (under 5), or "Out of Stock" badges with appropriate
colors. Include the block schema and Liquid template.
Working with JSON Templates
Shopify Online Store 2.0 uses JSON templates. Claude Code understands this structure:
> Add our new featured-collection-tabs section to the homepage
template. Place it between the hero banner and the newsletter
signup sections.
Claude Code reads templates/index.json, understands the section ordering, and inserts the reference correctly.
Code Review and Refactoring
Claude Code is exceptional at reviewing Shopify code for correctness, performance, and adherence to best practices.
Reviewing Liquid Code
> Review sections/product-main.liquid for:
- Performance issues (N+1 queries, unnecessary Liquid loops)
- Accessibility problems
- Missing null checks on objects
- SEO metadata gaps
- Mobile responsiveness issues
Refactoring Legacy Themes
Many Shopify stores run older themes that predate Online Store 2.0. Claude Code can modernize them:
> Refactor this product template from a sectioned theme (1.0) to
Online Store 2.0 format. Convert hardcoded content to section
settings and blocks. Preserve all existing functionality.
App Code Review
> Review the webhook handlers in app/webhooks/ for:
- HMAC verification on all endpoints
- Proper error handling and retry logic
- Idempotency (handling duplicate webhook deliveries)
- Response time (must respond within 5 seconds)
- Logging for debugging
When reviewing code, Claude Code checks against Shopify's actual requirements -- like the 5-second webhook response deadline, mandatory HMAC verification, and rate limiting thresholds. It does not just check syntax; it checks Shopify-specific correctness.
Writing Tests
Testing Shopify apps requires mocking Shopify's API responses, session handling, and webhook payloads. Claude Code generates comprehensive test suites.
Unit Tests for GraphQL Handlers
> Write Vitest tests for the products loader in app/routes/app.products.tsx.
Mock the GraphQL admin client and test:
- Successful product listing with pagination
- Empty product list handling
- GraphQL error responses
- Unauthenticated session redirect
Webhook Handler Tests
> Write tests for the ORDER_CREATED webhook handler. Include:
- Valid HMAC verification test
- Invalid HMAC rejection test
- Duplicate webhook idempotency test
- Malformed payload handling
- Database error recovery
End-to-End Theme Tests
> Write Playwright tests for the product page that verify:
- Variant selector updates price display
- Add to cart works and updates cart count
- Quantity selector respects inventory limits
- Image gallery navigation works
- Mobile responsive layout at 375px width
Debugging Production Issues
When things break in production, Claude Code becomes your debugging partner. Feed it error logs, and it will trace the issue.
Webhook Failures
> Here are the last 5 failed webhook deliveries from Shopify:
[paste webhook delivery details from Partner Dashboard]
Diagnose why these are failing and fix the issue.
Claude Code will analyze the error patterns, check your webhook handler code, identify the root cause (timeout, HMAC mismatch, unhandled payload structure), and implement the fix.
GraphQL Rate Limiting
> Our app is hitting Shopify's GraphQL rate limit during bulk
product syncs. The current code fetches products in a loop
without throttling. Fix this to respect the 2000-point bucket
with leak rate, and add proper cost tracking.
Theme Rendering Issues
> Customers report that product metafields show as blank on
some products but work on others. Here's the Liquid code:
{{ product.metafields.custom.care_instructions.value }}
Debug why this would be intermittent.
Creating a CLAUDE.md Template for Shopify Projects
Based on the workflows above, here is the recommended structure for your Shopify project's CLAUDE.md. Detailed templates are covered in the CLAUDE.md Template section, but here's the high-level structure:
# Project Name
## Overview
Brief project description and purpose.
## Tech Stack
Framework, language, database, UI library.
## Shopify Configuration
API version, app type, scopes, extensions.
## Commands
Dev server, build, test, deploy commands.
## File Structure
Key directories and their purposes.
## Coding Standards
Language-specific conventions and Shopify rules.
## Testing Requirements
Test framework, coverage expectations, what to test.
## Common Patterns
Recurring patterns specific to your project.
## Known Issues
Active bugs or workarounds Claude should know about.
Always include your Shopify API version in CLAUDE.md. Without it, Claude Code may default to a different version, generating code that references deprecated or non-existent fields. A single line like API Version: 2025-01 prevents hours of debugging.
Workflow Cheat Sheet
| Task | Prompt Pattern |
|---|---|
| New section | "Create a Liquid section called X that..." |
| GraphQL query | "Write a GraphQL query to fetch X with Y..." |
| Webhook handler | "Create a webhook handler for X that..." |
| Bug fix | "This error occurs when... [paste error]. Fix it." |
| Test suite | "Write tests for X covering Y, Z scenarios" |
| Refactor | "Refactor X to follow [pattern/standard]" |
| Code review | "Review X for [specific concerns]" |
| Migration | "Migrate X from [old] to [new]" |
Each of these patterns works because Claude Code has full access to your codebase. It reads the relevant files, understands the context, and makes changes that are consistent with the rest of your project.
Next Steps
Now that you understand the core workflows, proceed to Prompt Engineering for ready-to-use prompt templates that supercharge your Shopify development with Claude Code.