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

Do you already have access tokens?

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

Which API do you need?

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

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

Getting Started

API Clients

App Libraries

Session Storage

Guides

Choosing a Package

Choosing a Package

Quick Decision Tree

API Clients

@shopify/admin-api-client

@shopify/storefront-api-client

@shopify/graphql-client

@shopify/api-codegen-preset

App Building

@shopify/shopify-api

@shopify/shopify-app-express

@shopify/shopify-app-remix

Session Storage

Database Adapters

PostgreSQL

MySQL

MongoDB

Redis

SQLite

DynamoDB

Cloudflare KV

Memory (Dev Only)

ORM Adapters

Prisma

Drizzle

Common Combinations

Simple API Integration

Type-Safe API Client

Full Express App

Headless Storefront

Still Not Sure?

Try the Quickstart

View Examples

Ask the Community

Read the Guides

Getting Started

API Clients

App Libraries

Session Storage

Guides

​Choosing a Package

​Quick Decision Tree

​API Clients

​@shopify/admin-api-client

​@shopify/storefront-api-client

​@shopify/graphql-client

​@shopify/api-codegen-preset

​App Building

​@shopify/shopify-api

​@shopify/shopify-app-express

​@shopify/shopify-app-remix

​Session Storage

​Database Adapters

PostgreSQL

MySQL

MongoDB

Redis

SQLite

DynamoDB

Cloudflare KV

Memory (Dev Only)

​ORM Adapters

Prisma

Drizzle

​Common Combinations

​Simple API Integration

​Type-Safe API Client

​Full Express App

​Headless Storefront

​Still Not Sure?

Try the Quickstart

View Examples

Ask the Community

Read the Guides

Choosing a Package

Quick Decision Tree

API Clients

@shopify/admin-api-client

@shopify/storefront-api-client

@shopify/graphql-client

@shopify/api-codegen-preset

App Building

@shopify/shopify-api

@shopify/shopify-app-express

@shopify/shopify-app-remix

Session Storage

Database Adapters

ORM Adapters

Common Combinations

Simple API Integration

Type-Safe API Client

Full Express App

Headless Storefront

Still Not Sure?