Skip to main content

​
Installation

npm install @commerce-blocks/sdk

​
Configuration

​
Required Configuration

OptionTypeRequiredDescription
tokenstringYesLayers API public token
sortsSort[]YesSort options ({ name, code })
facetsFacet[]YesFacet fields ({ name, code })

​
Optional Configuration

OptionTypeDescription
attributesstring[]Product attributes to fetch
baseUrlstringCustom API URL
fetchCustomFetchCustom fetch implementation (SSR, testing)

​
Product Configuration

OptionTypeDescription
currencystringCurrency for price formatting
formatPrice(amount, currency) => stringCustom price formatter
swatchesSwatch[]Color swatch definitions
optionsstring[]Product options to expose
productMetafields{ namespace, key }[]Product metafields to fetch
variantMetafields{ namespace, key }[]Variant metafields to fetch
includeMetabooleanInclude _meta in results (experiments, applied rules, variant breakouts)

​
Transforms and Filter Aliases

Transforms post-process results before caching. Filter aliases map URL-friendly keys to API property names.
OptionTypeDescription
transforms.product({ base, raw }) => objectExtend products with custom fields
transforms.collection(result, raw) => resultTransform collection results
transforms.search(result, raw) => resultTransform search results
transforms.block(result, raw) => resultTransform block results
transforms.filters(filters) => FilterGroupCustom filter transformation
filterAliasesFilterAliasesURL-friendly filter key mapping
Once configured, transforms and aliases are applied automatically: 
import { createClient } from '@commerce-blocks/sdk'

const { data: client } = createClient({
  token: 'your-token',
  sorts: [{ name: 'Featured', code: 'featured' }],
  facets: [{ name: 'Color', code: 'options.color' }],
  attributes: ['body_html'],
  transforms: {
    product: ({ raw }) => ({
      description: raw.body_html ?? '',
      rating: raw.calculated?.average_rating ?? 0,
    }),
  },
  filterAliases: {
    color: 'options.color',
    size: 'options.size',
    brand: { property: 'vendor', values: { nike: 'Nike', adidas: 'Adidas' } },
  },
})

// Aliases resolve automatically
const collection = client.collection({ handle: 'shirts' })
await collection.execute({ filters: { color: 'Red', brand: 'nike' } })
// Products now include description and rating from the product transform

​
Cache Configuration

OptionTypeDescription
cacheLimitnumberMax entries in cache
cacheLifetimenumberTTL in milliseconds
storageStorageAdapterCustom storage adapter for cache persistence (defaults to localStorage in browser)
initialDataCacheDataPre-populate cache at initialization
restoreCachebooleanAuto-restore from storage on init (default: true)

​
Singleton Access

After initialization, access the client anywhere: 
import { getClient, isInitialized } from '@commerce-blocks/sdk'

if (isInitialized()) {
  const { data: client } = getClient()
  if (client) {
    // Use client
  }
}

​
Important Notes

All SDK methods return a Result type instead of throwing exceptions. Always check for result.error before accessing result.data.