A TypeScript SDK for the Shopify Storefront API that provides a simple and intuitive interface for interacting with Shopify's GraphQL API.
npm install @devxcommerce/shopifyA TypeScript SDK for the Shopify Storefront API that provides a simple and intuitive interface for interacting with Shopify's GraphQL API.
- 🚀 Type-safe: Written in TypeScript with full type definitions
- 🔄 Modern: Uses modern JavaScript features and ESM/CJS dual package support
- 🌐 Comprehensive: Supports Shopify Storefront API operations for:
- Products and Collections
- Cart Management
- Customer Accounts and Addresses
- Orders
- Pages and Menus
- Metafields
- Files
- 🔒 Secure: Best practices for API authentication
- 🧩 Modular: Organized code structure for better maintainability
``bashnpm
npm install @devxcommerce/shopify
Getting Started
$3
typescript
import { ShopifySDK } from '@devxcommerce/shopify';const sdk = new ShopifySDK({
domain: 'your-store.myshopify.com',
apiVersion: '2023-07', // Use current API version
accessToken: 'your-storefront-access-token',
// Optional: For admin API access
adminAccessToken: 'your-admin-access-token',
});
`$3
Fetch products from your Shopify store:
typescript
// List products
const products = await sdk.products.list({
variables: { first: 10 },
});// Get product by ID
const product = await sdk.products.getById({
variables: { id: 'gid://shopify/Product/123' },
});
// Get product by handle
const product = await sdk.products.getByHandle({
variables: { handle: 'my-product' },
});
// Get product recommendations
const recommendations = await sdk.products.getRecommendations({
variables: { productId: 'gid://shopify/Product/123' },
});
// List product variants
const variants = await sdk.products.listVariants({
variables: {
handle: 'my-product',
first: 10,
},
});
// List product images
const images = await sdk.products.listImages({
variables: {
handle: 'my-product',
first: 10,
},
});
`$3
Work with collections in your Shopify store:
typescript
// List collections
const collections = await sdk.collections.list({
variables: { first: 10 },
});// Get collection by ID
const collection = await sdk.collections.getById({
variables: { id: 'gid://shopify/Collection/123' },
});
// Get collection by handle
const collection = await sdk.collections.getByHandle({
variables: { handle: 'featured-products' },
});
// List products in a collection
const products = await sdk.collections.listProducts({
variables: {
handle: 'featured-products',
first: 10,
},
});
`$3
Manage shopping carts:
typescript
// Create a cart
const cart = await sdk.cart.create();// Add items to cart
const updatedCart = await sdk.cart.addLines({
variables: {
cartId: cart.id,
lines: [
{
merchandiseId: 'gid://shopify/ProductVariant/123',
quantity: 1,
},
],
},
});
// Update cart items
const updatedCart = await sdk.cart.updateLines({
variables: {
cartId: cart.id,
lines: [
{
id: 'existing-line-item-id',
quantity: 2,
},
],
},
});
// Remove items from cart
const updatedCart = await sdk.cart.removeLines({
variables: {
cartId: cart.id,
lineIds: ['line-item-id-to-remove'],
},
});
// Get cart by ID
const cart = await sdk.cart.get({
variables: { id: 'cart-id' },
});
`$3
Manage customer accounts:
typescript
// Create customer account
const customer = await sdk.customer.create({
variables: {
input: {
firstName: 'John',
lastName: 'Doe',
email: 'john.doe@example.com',
password: 'password123',
},
},
});// Customer login
const accessToken = await sdk.customer.createCAT({
variables: {
input: {
email: 'john.doe@example.com',
password: 'password123',
},
},
});
// Get customer information
const customer = await sdk.customer.getProfile({
variables: {
customerAccessToken: 'customer-access-token',
},
});
// Update customer information
const updatedCustomer = await sdk.customer.updateProfile({
variables: {
customerAccessToken: 'customer-access-token',
customer: {
firstName: 'John',
lastName: 'Smith',
},
},
});
`$3
The SDK provides a consistent error handling pattern:
typescript
import { ShopifySDK, ShopifyError } from '@devxcommerce/shopify';try {
const products = await sdk.products.list({
variables: { first: 10 },
});
} catch (error) {
if (error instanceof ShopifyError) {
console.error(
Error (${error.statusCode}): ${error.message}); // If there are specific GraphQL errors
if (error.errors) {
console.error('Detailed errors:', error.errors);
}
} else {
console.error('Unknown error:', error);
}
}
`Advanced Usage
$3
You can execute custom GraphQL queries directly:
typescript
const data = await sdk.fetch({
query: ,
variables: {},
});
`$3
For operations that require Admin API access:
typescript
// Note: Admin API requests can only be performed server-side
const data = await sdk.fetchAdmin({
query: ,
variables: {},
});
`API Reference
The SDK provides the following classes, each with methods for interacting with different parts of the Shopify Storefront API:
$3
The main SDK class that provides access to all other modules.
Constructor:
-
- Initializes the SDK with configurationMethods:
-
fetch - Execute Storefront API queries
- fetchAdmin - Execute Admin API queries (server-side only)$3
Access product-related operations.
Methods:
-
list({ variables, options }) - Get a list of products`typescript
const products = await sdk.products.list({
variables: {
first: 10,
sortKey: 'TITLE',
reverse: false,
},
});
`-
- Get a product by ID`typescript
const product = await sdk.products.getById({
variables: {
id: 'gid://shopify/Product/123456789',
metafields: ['namespace.key'], // optional, to include metafields
},
});
`-
- Get a product by handle`typescript
const product = await sdk.products.getByHandle({
variables: {
handle: 'my-awesome-product',
metafields: ['reviews.rating'], // optional
},
});
`-
- Get a product by ID or handle`typescript
// Using ID
const product = await sdk.products.get({
variables: { id: 'gid://shopify/Product/123456789' },
});// Using handle
const product = await sdk.products.get({
variables: { handle: 'my-awesome-product' },
});
`-
- Get product recommendations`typescript
const recommendations = await sdk.products.getRecommendations({
variables: { productId: 'gid://shopify/Product/123456789' },
});
`-
- Get a list of product variants`typescript
// By product ID
const variants = await sdk.products.listVariants({
variables: {
productId: 'gid://shopify/Product/123456789',
first: 20,
},
});// By product handle
const variants = await sdk.products.listVariants({
variables: {
productHandle: 'my-awesome-product',
first: 20,
},
});
`-
- Get a list of product images`typescript
// By product ID
const images = await sdk.products.listImages({
variables: {
productId: 'gid://shopify/Product/123456789',
first: 10,
},
});// By product handle
const images = await sdk.products.listImages({
variables: {
productHandle: 'my-awesome-product',
first: 10,
},
});
`$3
Access collection-related operations.
Methods:
-
- Get a list of collections`typescript
const collections = await sdk.collections.list({
variables: {
first: 10,
sortKey: 'TITLE',
},
});
`-
- Get a collection by ID`typescript
const collection = await sdk.collections.getById({
variables: {
id: 'gid://shopify/Collection/123456789',
metafields: ['custom.featured'], // optional
},
});
`-
- Get a collection by handle`typescript
const collection = await sdk.collections.getByHandle({
variables: {
handle: 'summer-collection',
metafields: ['custom.season'], // optional
},
});
`-
- Get a collection by ID or handle`typescript
// Using ID
const collection = await sdk.collections.get({
variables: { id: 'gid://shopify/Collection/123456789' },
});// Using handle
const collection = await sdk.collections.get({
variables: { handle: 'summer-collection' },
});
`-
- Get products in a collection by ID`typescript
const products = await sdk.collections.listProductsById({
variables: {
id: 'gid://shopify/Collection/123456789',
first: 20,
sortKey: 'BEST_SELLING',
},
});
`-
- Get products in a collection by handle`typescript
const products = await sdk.collections.listProductsByHandle({
variables: {
handle: 'summer-collection',
first: 20,
sortKey: 'PRICE',
reverse: true, // descending
},
});
`-
- Get products in a collection by ID or handle`typescript
// Using ID
const products = await sdk.collections.listProducts({
variables: {
id: 'gid://shopify/Collection/123456789',
first: 20,
},
});// Using handle
const products = await sdk.collections.listProducts({
variables: {
handle: 'summer-collection',
first: 20,
},
});
`-
- Get filtered product IDs in a collection`typescript
const productIds = await sdk.collections.listFilteredProductIds({
variables: {
handle: 'summer-collection',
filters: [
{
price: { min: 10, max: 100 },
},
{
available: true,
},
],
},
});
`$3
Manage cart operations.
Methods:
-
- Get a cart by ID-
create({ variables, options }) - Create a new cart
- updateLines({ variables, options }) - Update lines in a cart
- addLines({ variables, options }) - Add lines to a cart
- removeLines({ variables, options }) - Remove lines from a cart
- updateAttributes({ variables, options }) - Update cart attributes
- updateDiscountCodes({ variables, options }) - Update cart discount codes$3
Manage customer accounts.
Methods:
-
create({ variables, options }) - Create a new customer account
- updateProfile({ variables, options }) - Update a customer's profile
- getProfile({ variables, options }) - Get a customer's profile
- createCAT({ variables, options }) - Create a customer access token (login)
- createCATWithMultipass({ variables, options }) - Create customer access token with Multipass
- activate({ variables, options }) - Activate a customer account
- activateByUrl({ variables, options }) - Activate a customer account by URL
- update({ variables, options }) - Update a customer
- customerEmailMarketingConsentUpdate({ variables, options }) - Update email marketing consent
- list({ variables, options }) - List customers (admin only)
- subscribeToNewsletter({ variables, options }) - Subscribe to newsletter
- generateAccountActivationUrl({ variables, options }) - Generate account activation URL
- createFromAdmin({ variables, options }) - Create customer from admin$3
Manage customer addresses.
Methods:
-
list({ variables, options }) - Get a list of customer addresses
- create({ variables, options }) - Create a customer address
- update({ variables, options }) - Update a customer address
- delete({ variables, options }) - Delete a customer address
- makeDefault({ variables, options }) - Set address as default$3
Access order-related operations.
Methods:
-
list({ variables, options }) - Get a list of customer orders
- get({ variables, options }) - Get an order by ID$3
Access page content.
Methods:
-
get({ variables, options }) - Get a page by handle
- list({ variables, options }) - Get a list of pages
- getById({ variables, options }) - Get a page by ID
- getByHandle({ variables, options }) - Get a page by handle$3
Access navigation menus.
Methods:
-
get({ variables, options }) - Get a menu by handle$3
Access metafield operations.
Methods:
-
list({ variables, options }) - Get a list of metafields for a resource
- listByType({ variables, options }) - Get a list of metafields by type$3
Access file operations.
Methods:
-
create({ variables, options }) - Create a file
- get({ variables, options }) - Get a file by ID
- delete({ variables, options })` - Delete a fileThis SDK is written in TypeScript and includes comprehensive type definitions for all Shopify Storefront API objects and operations.
ISC
Kritik Jiyaviya (kritik.jiyaviya@devxconsultancy.com)