SDK overview

The Layers SDK (@commerce-blocks/sdk) is an ES module SDK for product discovery powered by the Layers API. It provides reactive state management, built-in caching, and a unified interface for browse, search, recommendations, and image search.

Key features

Layers API integration

Full access to Layers’ search, browse, recommendations, blocks, and image search APIs with built-in error handling.

Reactive state management

Framework-agnostic reactive controllers with subscribe() for automatic UI updates and in-flight request deduplication.

Product card controller

Reactive product card management with variant selection, availability logic, and automatic state updates.

Extensibility

Transform products, collections, search, blocks, and other responses with custom transforms. Build filters with a type-safe DSL.

Quick start

import { createSDK } from '@commerce-blocks/sdk'

const { data: sdk, error } = createSDK({
  storefrontAccessToken: 'your-storefront-token',
  trackingToken: 'your-tracking-token',
  currencyCode: 'USD',
})

if (error) {
  console.error('SDK init failed:', error.message)
} else {
  const collection = sdk.collection({ collectionHandle: 'shirts' })
  const result = await collection.get()

  if (result.data) {
    console.log(result.data.products)
  }

  collection.dispose()
}

SDK methods

The SDK returns controllers for all Layers storefront APIs:

Method	Description
`sdk.collection()`	Browse and filter products within merchandised collections
`sdk.search()`	Semantic product search with prepare/get flow
`sdk.autocomplete()`	Predictive search suggestions
`sdk.suggest()`	Deprecated autocomplete wrapper with built-in debounce
`sdk.blocks()`	Product recommendations powered by Layers blocks
`sdk.uploadImage()`	Upload images for image-based search
`sdk.imageSearch()`	Search products using uploaded images
`sdk.searchByImage()`	Deprecated alias for `imageSearch()`
`sdk.searchContent()`	Search articles and blog content
`sdk.similarProducts()`	Find products similar to a given product
`sdk.facets()`	Fetch facet counts and ranges for a collection
`sdk.sortOrders()`	Fetch available sort options at runtime
`sdk.searchFeedback()`	Send search-quality feedback
`sdk.trackingEvent()`	Send analytics events via `sendBeacon` with a fetch fallback
`createProductCard()`	Reactive product card with variant selection and availability logic

Architecture

The SDK uses a controller pattern where each method returns a controller with reactive state and a get() method. All controllers support two ways to consume state:

import { subscribe } from '@commerce-blocks/sdk'

const collection = sdk.collection({
  collectionHandle: 'shirts',
  sort: 'featured',
})

// 1. Controller subscribe (no extra import needed)
const unsubscribe = collection.subscribe(({ data, error, loading }) => {
  if (loading) console.log('Loading...')
  if (error) console.error('Error:', error.message)
  if (data) console.log('Products:', data.products)
})

// 2. Standalone subscribe utility
const unsubscribe2 = subscribe(collection, (state) => {
  console.log('State changed:', state)
})

// Read current state synchronously
const { data, loading, error } = collection.state

// Fetch results
await collection.get() // initial load
await collection.get({ pagination: { page: 2 } }) // pagination
await collection.get({ sort: 'price_asc' }) // change sort

// Cleanup
unsubscribe()
unsubscribe2()
collection.dispose()

Next steps

Installation

Learn how to install and configure the SDK in your project.

API reference

Explore the complete API reference for all SDK methods.

Framework integration

Patterns for React, Vue, Svelte, Lit, Alpine.js, and vanilla JS.

Error handling

Learn how to handle errors gracefully with the Result pattern.

Overview

SDK Reference

SDK Guides

Changelog & Upgrades

AI Enablement

Key features

Layers API integration

Reactive state management

Product card controller

Extensibility

Quick start

SDK methods

Architecture

Next steps

Installation

API reference

Framework integration

Error handling

​Key features

Layers API integration

Reactive state management

Product card controller

Extensibility

​Quick start

​SDK methods

​Architecture

​Next steps

Installation

API reference

Framework integration

Error handling

Key features

Quick start

SDK methods

Architecture

Next steps