shopify-sdk-patterns

name	shopify-sdk-patterns
description	Apply production-ready patterns for @shopify/shopify-api including typed GraphQL clients, session management, and retry logic. Use when implementing Shopify integrations, refactoring SDK usage, or establishing team coding standards for Shopify. Trigger with phrases like "shopify SDK patterns", "shopify best practices", "shopify code patterns", "idiomatic shopify", "shopify client wrapper".
allowed-tools	Read, Write, Edit
version	2.7.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","ecommerce","shopify"]
compatibility	Designed for Claude Code

Shopify SDK Patterns

Overview

Production-ready patterns for the @shopify/shopify-api library: singleton clients, typed GraphQL operations, session management, cursor-based pagination, codegen-typed operations, bulk operations, and webhook registry patterns.

Prerequisites

• @shopify/shopify-api v9+ installed
• Familiarity with Shopify's GraphQL Admin API
• Understanding of async/await and TypeScript generics

Instructions

Step 1: Typed GraphQL Client Wrapper

Initialize a singleton shopifyApi instance with LATEST_API_VERSION, cache sessions per shop, and expose a typed shopifyQuery<T>() helper that wraps client.request().

See Typed GraphQL Client for the complete implementation.

Step 2: Error Handling with Shopify Error Types

Custom ShopifyServiceError class that distinguishes retryable errors (429, 5xx) from permanent ones. Includes handleShopifyError() for error translation and safeShopifyCall() that returns {data, error} tuples instead of throwing.

See Error Handling for the complete implementation.

Step 3: Cursor-Based Pagination

Async generator paginateShopify<T>() for Relay-style cursor pagination. Yields batches of nodes, automatically following pageInfo.endCursor until hasNextPage is false. Memory-efficient for large datasets.

See Cursor Pagination for the complete implementation.

Step 4: Multi-Tenant Client Factory

ShopifyClientFactory class for apps installed on multiple stores. Creates isolated GraphqlClient instances per merchant with session caching. Includes removeClient() for eviction on app uninstall.

See Multi-Tenant Factory for the complete implementation.

Step 5: Codegen-Typed Operations

Use @shopify/api-codegen-preset to generate TypeScript types from your GraphQL operations. This eliminates manual type definitions and catches schema changes at build time.

// codegen.ts — project root config
 { shopifyApiProject,  }  ;

  {
  : ,
  : [],
  : {
    : ({
      : .,
      : , 
      : ,
    }),
  },
};