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.

Development

Setup for Contributors

If you're contributing to this project, follow these steps to set up your development environment:

1. Install dependencies:

   pnpm install

2. Set up Git hooks (lefthook):

   pnpm exec lefthook install

   This sets up pre-commit hooks for code formatting, type checking, and testing.

3. Create environment file: Copy .env.example to .env and fill in your Shopify API credentials.

Available Scripts

In the package.json file, you will find several scripts for development:

• pnpm build: Compiles the TypeScript source code into JavaScript files in the dist directory.
• pnpm watch: Watches for changes in GraphQL schema and documents and automatically regenerates TypeScript types.
• pnpm ci: Runs a full continuous integration check, including formatting, dependency analysis, export validation, and tests.
• pnpm format:check: Checks the codebase for formatting and linting issues using Biome.
• pnpm format:fix: Automatically fixes formatting and linting issues.
• pnpm check-exports: Verifies that the package's entry points are correctly configured for different module systems.
• pnpm test: Runs the test suite using Vitest.
• pnpm test:watch: Runs the test suite in watch mode, re-running tests on file changes.
• pnpm typecheck: Runs the TypeScript compiler to check for type errors without emitting files.
• pnpm knip: Detects unused files, dependencies, and exports in the project.
• pnpm codegen: Generates TypeScript types from GraphQL operations.