Shopify Client Library

A TypeScript library for interacting with the Shopify Admin API.

Features

• Dual Module Support: Supports both ESM and CommonJS for maximum compatibility.
• Type-Safe: Generated types for GraphQL operations and Zod schemas for output validation only.
• Modular: Each API call is a self-contained function.
• Tested: Tests for each module.

Getting Started

Installation

To install the library, run:

pnpm install @ehrenkind/shopify-lib

Usage Examples

This library supports both ESM and CommonJS module systems for maximum compatibility.

ESM Project Setup

For an ESM project, ensure your package.json includes:

{
  "type": "module"
}

TypeScript configuration (tsconfig.json):

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true
  }
}

Usage in ESM:

import { getLeanProductVariants, getOrderByName } from '@ehrenkind/shopify-lib';

// Fetch product variants by SKUs
const skus = ['SKU123', 'SKU456'];
const variants = await getLeanProductVariants(skus);
console.log('Product variants:', variants);

// Fetch order by name
const order = await getOrderByName('1001');
console.log('Order details:', order);

CommonJS Project Setup

For a CommonJS project, ensure your package.json does NOT include "type": "module" (or explicitly set "type": "commonjs"):

{
  "type": "commonjs"
}

TypeScript configuration (tsconfig.json):

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "CommonJS",
    "moduleResolution": "node",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true
  }
}

Usage in CommonJS:

const { getLeanProductVariants, getOrderByName } = require('@ehrenkind/shopify-lib');

async function fetchData() {
  try {
    // Fetch product variants by SKUs
    const skus = ['SKU123', 'SKU456'];
    const variants = await getLeanProductVariants(skus);
    console.log('Product variants:', variants);

    // Fetch order by name
    const order = await getOrderByName('1001');
    console.log('Order details:', order);
  } catch (error) {
    console.error('Error fetching data:', error);
  }
}

fetchData();

Alternative CommonJS usage with Promises:

const { getLeanProductVariants, getOrderByName } = require('@ehrenkind/shopify-lib');

// Using .then() syntax
const skus = ['SKU123', 'SKU456'];
getLeanProductVariants(skus)
  .then(variants => {
    console.log('Product variants:', variants);
    return getOrderByName('1001');
  })
  .then(order => {
    console.log('Order details:', order);
  })
  .catch(error => {
    console.error('Error:', error);
  });

Environment Setup

Both ESM and CommonJS projects need the same environment variables. Create a .env file in your project root:

SHOPIFY_API_KEY=your_api_key_here
SHOPIFY_API_SECRET=your_api_secret_here
SHOPIFY_API_HOSTNAME=your-shop.myshopify.com
SHOPIFY_ACCESS_TOKEN=your_access_token_here

Key Features

Input/Output Validation with Zod

We use Zod to validate the output of every exported function. This ensures the consuming code is always safe to use and things don't break down the line.

GraphQL Code Generation

All TypeScript types for GraphQL queries and mutations are automatically generated and stored in src/generated-api-types/. This provides compile-time type safety and reduces boilerplate code when making API requests.

API Call Organization

API calls are organized into queries and mutations and have the same name as the GraphQL operation in the documentation: https://shopify.dev/docs/api/admin-graphql/latest/. Each module corresponds to a specific Shopify entity or use case (e.g., productVariants, metaobjects), making the codebase easy to navigate and maintain.

Testing

Each module includes a corresponding test file (e.g., getLeanProductVariants.ts has getLeanProductVariants.test.ts). This ensures that every API interaction is thoroughly tested, guaranteeing reliability. For mocks add a file with the same name but with .mock.ts at the end, like getLeanProductVariants.mock.ts and add the handlers to src/utils/mswHandlers.ts. The mocks use MSW to mock the API responses.

Contributing

See CONTRIBUTING.md for development setup, available scripts, code organization guidelines, and release process.