Best practices

This guide covers best practices for SDK setup, controller lifecycle management, and common mistakes to avoid.

SDK initialization

Create the SDK once

Create a single SDK instance and share it across your application. Creating multiple instances wastes resources and breaks caching.

// Bad - creates multiple SDK instances
function SearchComponent() {
  const { data: sdk } = createSDK({
    storefrontAccessToken: 'your-storefront-token',
    trackingToken: 'your-tracking-token',
  })
  // Creates a new SDK instance on every render
}

// Good - create once, share globally
const { data: sdk, error } = createSDK({
  storefrontAccessToken: 'your-storefront-token',
  trackingToken: 'your-tracking-token',
})

if (error) {
  console.error('SDK init failed:', error.message)
}

function SearchComponent() {
  const search = sdk.search({ query: 'shoes' })
  // ...
}

Required configuration

storefrontAccessToken and trackingToken are required. All other options are optional.

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

if (error) {
  console.error('SDK init failed:', error.message)
}

sorts and facets arrays are no longer passed to createSDK(). Fetch them at runtime with sdk.sortOrders() and sdk.facets().

Controller lifecycle

Always dispose controllers

Controllers maintain subscriptions and state. Dispose them when components unmount to prevent memory leaks and abort stale requests.

// Bad - memory leak
function SearchComponent() {
  const search = sdk.search({ query: 'shoes' })
  // Component unmounts but the controller keeps running
}

// Good - cleanup on unmount
function SearchComponent() {
  const search = sdk.search({ query: 'shoes' })

  onUnmount(() => search.dispose()) // framework-specific cleanup
}

Use `get()` for shallow updates

In v3, query parameters are set when the controller is created and shallow-merged by get(). Use get() for pagination, sort, and filter changes.

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

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

Do not create a new controller for every small update if the same query context can be reused. Create a new controller only when the core query changes (for example, a new search term).

Create new controllers for new search queries

A search controller is created for a specific query. To search for a different term, create a new controller.

function search(query) {
  const search = sdk.search({ query })
  search.get().then(({ data, error }) => {
    if (error) {
      console.error('Search failed:', error.message)
    } else if (data) {
      renderProducts(data.products)
    }
  })
  return search
}

Filter handling

Use the filter DSL for complex filters

For explicit control, use the filter DSL instead of hand-writing filter objects.

import { filter, and, eq } from '@commerce-blocks/sdk'

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

await collection.get({
  filterGroup: filter(and(
    eq('your-attribute', 'your-value'),
    eq('your-attribute-2', 'your-value-2'),
  )),
})

Replace your-attribute and your-value with the attribute codes configured in your Layers dashboard. In v3, facets and sort orders are not configured at SDK init. Fetch them at runtime.

const sortController = sdk.sortOrders()
const { data: sortData, error: sortError } = await sortController.get()
if (!sortError && sortData) {
  renderSortDropdown(sortData.sortOrders)
}

const facetController = sdk.facets({ collectionHandle: 'shirts' })
const { data: facetData, error: facetError } = await facetController.get()
if (!facetError && facetData) {
  renderFacets(facetData.facets)
}

Error handling

Handle errors gracefully

Always check for errors in the Result object:

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

const search = sdk.search({ query: 'shoes' })
const { data, error } = await search.get()

if (error) {
  if (error instanceof ApiError && error.status === 429) {
    showError('Too many requests. Please wait a moment.')
  } else {
    showError('Search failed. Please try again.')
  }
  return
}

renderProducts(data.products)

Prepare failures are non-fatal

If search.prepare() fails, search.get() still works, but it may take longer because the query is prepared on demand.

const search = sdk.search({ query: 'shoes' })
const { error: prepareError } = await search.prepare()

if (prepareError) {
  console.warn('Prepare failed. get() will still work, but may be slower.')
}

const { data, error } = await search.get()
if (error) {
  console.error('Search failed:', error.message)
} else if (data) {
  renderProducts(data.products)
}

Caching

Use `storage` for cache persistence

The SDK caches data in memory by default. For cache persistence across page loads, pass a storage backend.

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

Overview

SDK Reference

SDK Guides

Changelog & Upgrades

AI Enablement

Best practices

SDK initialization

Create the SDK once

Required configuration

Controller lifecycle

Always dispose controllers

Use `get()` for shallow updates

Create new controllers for new search queries

Filter handling

Use the filter DSL for complex filters

Fetch facets and sort orders at runtime

Error handling

Handle errors gracefully

Prepare failures are non-fatal

Caching

Use `storage` for cache persistence

Next steps

Search patterns

Caching

​SDK initialization

​Create the SDK once

​Required configuration

​Controller lifecycle

​Always dispose controllers

​Use get() for shallow updates

​Create new controllers for new search queries

​Filter handling

​Use the filter DSL for complex filters

​Fetch facets and sort orders at runtime

​Error handling

​Handle errors gracefully

​Prepare failures are non-fatal

​Caching

​Use storage for cache persistence

​Next steps

Search patterns

Caching

SDK initialization

Create the SDK once

Required configuration

Controller lifecycle

Always dispose controllers

Use `get()` for shallow updates

Create new controllers for new search queries

Filter handling

Use the filter DSL for complex filters

Fetch facets and sort orders at runtime

Error handling

Handle errors gracefully

Prepare failures are non-fatal

Caching

Use `storage` for cache persistence

Next steps