Skip to main content

​
Choosing a Package

The Shopify App JavaScript SDK is organized as a monorepo with multiple packages. This guide will help you choose the right packages for your needs.

​
Quick Decision Tree

1

Do you already have access tokens?

Yes → Use the API Client packagesNo → You need the App Building packages to handle OAuth
2

Which API do you need?

  • Admin API → @shopify/admin-api-client
  • Storefront API → @shopify/storefront-api-client
  • Both or custom → @shopify/graphql-client
3

Building a full app?

  • Framework-agnostic → @shopify/shopify-api
  • Using Express → @shopify/shopify-app-express
  • Using Remix → @shopify/shopify-app-remix

​
API Clients

These packages are lightweight clients for interacting with Shopify’s APIs. Use these when you:
  • Already have access tokens (from a custom app or OAuth flow)
  • Want minimal dependencies and framework-agnostic code
  • Need to make API requests without full app infrastructure

​
@shopify/admin-api-client

Best for: Interacting with the Admin API (both GraphQL and REST) 
npm install @shopify/admin-api-client
Features:
  • GraphQL and REST API support
  • Automatic retry handling for 429 and 503 responses
  • Built-in type definitions
  • Configurable logging for debugging
Use cases:
  • Querying products, orders, customers
  • Managing inventory and fulfillments
  • Creating and updating store resources
  • Admin app backends
Example: 
import {createAdminApiClient} from '@shopify/admin-api-client';

const client = createAdminApiClient({
  storeDomain: 'your-shop-name.myshopify.com',
  apiVersion: '2024-01',
  accessToken: 'your-admin-api-access-token',
});

const {data} = await client.request(`
  query {
    shop {
      name
      email
    }
  }
`);
View full documentation →

​
@shopify/storefront-api-client

Best for: Building customer-facing features with the Storefront API 
npm install @shopify/storefront-api-client
Features:
  • GraphQL Storefront API support
  • Support for @defer directive and streaming responses
  • Public and private access token support
  • CDN delivery for browser usage
Use cases:
  • Custom storefronts and headless commerce
  • Product catalogs and collections
  • Shopping cart management
  • Customer account integration
Example: 
import {createStorefrontApiClient} from '@shopify/storefront-api-client';

const client = createStorefrontApiClient({
  storeDomain: 'your-shop-name.myshopify.com',
  apiVersion: '2024-01',
  publicAccessToken: 'your-storefront-public-access-token',
});

const {data} = await client.request(`
  query ProductQuery($handle: String!) {
    product(handle: $handle) {
      id
      title
      priceRange {
        minVariantPrice {
          amount
          currencyCode
        }
      }
    }
  }`,
  {
    variables: {handle: 'sample-product'},
  }
);
View full documentation →

​
@shopify/graphql-client

Best for: Generic GraphQL client for any Shopify API or custom needs 
npm install @shopify/graphql-client
Features:
  • Works with any GraphQL API
  • Full control over URL and headers
  • Stream response support
  • Runtime-agnostic (Node.js, browser, edge)
Use cases:
  • Multiple API access in one app
  • Custom authentication requirements
  • Non-standard Shopify APIs
  • Testing and development
Example: 
import {createGraphQLClient} from '@shopify/graphql-client';

const client = createGraphQLClient({
  url: 'https://your-shop-name.myshopify.com/api/2024-01/graphql.json',
  headers: {
    'Content-Type': 'application/json',
    'X-Shopify-Storefront-Access-Token': 'your-token',
  },
  retries: 1,
});
View full documentation →

​
@shopify/api-codegen-preset

Best for: Adding TypeScript type safety to your GraphQL queries 
npm install --save-dev @shopify/api-codegen-preset
Features:
  • Automatic type generation from GraphQL operations
  • Integrates with graphql-codegen
  • Support for all Shopify APIs
  • Watch mode for development
Use cases:
  • TypeScript projects requiring type safety
  • Large codebases with many queries
  • Teams wanting autocomplete and validation
  • Preventing runtime type errors
Example: 
// .graphqlrc.ts
import {ApiType, shopifyApiProject} from '@shopify/api-codegen-preset';

export default {
  schema: 'https://shopify.dev/admin-graphql-direct-proxy',
  documents: ['*.ts', '!node_modules'],
  projects: {
    default: shopifyApiProject({
      apiType: ApiType.Admin,
      apiVersion: '2024-01',
      outputDir: './types',
    }),
  },
};
View full documentation →

​
App Building

These packages help you build complete Shopify apps with OAuth, webhooks, session management, and more.

​
@shopify/shopify-api

Best for: Framework-agnostic Shopify app infrastructure 
npm install @shopify/shopify-api
Features:
  • OAuth authentication flow
  • Webhook registration and processing
  • Session management
  • REST resources and GraphQL clients
  • Billing API integration
  • Runtime adapters (Node.js, Cloudflare Workers, Web API)
Use cases:
  • Building apps with any framework
  • Custom server implementations
  • Serverless and edge deployments
  • Apps requiring full control over architecture
Requires:
  • Manual route setup
  • Session storage implementation
  • Webhook handler configuration
Example: 
import '@shopify/shopify-api/adapters/node';
import {shopifyApi, ApiVersion} from '@shopify/shopify-api';

const shopify = shopifyApi({
  apiKey: 'your-api-key',
  apiSecretKey: 'your-api-secret',
  scopes: ['read_products', 'write_orders'],
  hostName: 'your-app-domain.com',
  apiVersion: ApiVersion.January24,
});
View full documentation →

​
@shopify/shopify-app-express

Best for: Express.js apps with middleware and route handlers 
npm install @shopify/shopify-app-express
Features:
  • Express middleware for authentication
  • Pre-built OAuth routes
  • Webhook processing middleware
  • Session token validation
  • Built on top of @shopify/shopify-api
Use cases:
  • Express.js applications
  • Traditional server-rendered apps
  • Apps with existing Express infrastructure
  • Quick prototypes and MVPs
Example: 
import express from 'express';
import {shopifyApp} from '@shopify/shopify-app-express';

const shopify = shopifyApp({
  api: {
    apiKey: 'your-api-key',
    apiSecretKey: 'your-api-secret',
    scopes: ['read_products'],
    hostName: 'your-app-domain.com',
  },
  auth: {
    path: '/api/auth',
    callbackPath: '/api/auth/callback',
  },
});

const app = express();

app.get(shopify.config.auth.path, shopify.auth.begin());
app.get(
  shopify.config.auth.callbackPath,
  shopify.auth.callback(),
  shopify.redirectToShopifyOrAppRoot(),
);
View full documentation →

​
@shopify/shopify-app-remix

Best for: Remix framework applications 
npm install @shopify/shopify-app-remix
Features:
  • Remix loader and action utilities
  • Automatic OAuth handling
  • Session management with Remix sessions
  • TypeScript-first development
  • Built on top of @shopify/shopify-api
Use cases:
  • Modern Remix applications
  • Full-stack TypeScript apps
  • Apps using Shopify’s official templates
  • Progressive enhancement patterns
View full documentation →

​
Session Storage

When building a full Shopify app, you need to store sessions. Choose a storage adapter based on your database:

​
Database Adapters

PostgreSQL

@shopify/shopify-app-session-storage-postgresql

MySQL

@shopify/shopify-app-session-storage-mysql

MongoDB

@shopify/shopify-app-session-storage-mongodb

Redis

@shopify/shopify-app-session-storage-redis

SQLite

@shopify/shopify-app-session-storage-sqlite

DynamoDB

@shopify/shopify-app-session-storage-dynamodb

Cloudflare KV

@shopify/shopify-app-session-storage-kv

Memory (Dev Only)

@shopify/shopify-app-session-storage-memory

​
ORM Adapters

Prisma

@shopify/shopify-app-session-storage-prisma

Drizzle

@shopify/shopify-app-session-storage-drizzle
Example: 
import {PostgreSQLSessionStorage} from '@shopify/shopify-app-session-storage-postgresql';

const sessionStorage = new PostgreSQLSessionStorage(
  'postgresql://username:password@localhost/database'
);

const shopify = shopifyApi({
  // ... other config
  sessionStorage,
});

​
Common Combinations

​
Simple API Integration

npm install @shopify/admin-api-client
Perfect for scripts, background jobs, or simple integrations where you already have an access token.

​
Type-Safe API Client

npm install @shopify/admin-api-client
npm install --save-dev @shopify/api-codegen-preset
Add type safety to your API client with automatic code generation.

​
Full Express App

npm install @shopify/shopify-app-express
npm install @shopify/shopify-app-session-storage-postgresql
Complete app infrastructure with Express and PostgreSQL session storage.

​
Headless Storefront

npm install @shopify/storefront-api-client
npm install --save-dev @shopify/api-codegen-preset
Build custom storefronts with type-safe Storefront API access.

​
Still Not Sure?

Try the Quickstart

Start with the Admin API Client and expand from there

View Examples

See real-world code examples for different use cases

Ask the Community

Get help from other developers

Read the Guides

Deep dive into OAuth, webhooks, and more

Build docs developers (and LLMs) love

Get started for freeTalk to us