Caching

The SDK caches controller responses in an in-memory LRU to minimize API calls and improve performance. The cache lasts for the life of the page. Optional storage persists prepared search IDs, not controller responses, so a later page can reuse the prepare step.

Request deduplication

When multiple controllers request the same data, the SDK deduplicates in-flight requests and reuses cached results:

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

await Promise.all([
  collection1.get(),
  collection2.get(),
])

// Only ONE network request is made

Cache configuration

Control cache behavior with the cache option at SDK initialization:

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

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

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

Option	Type	Description
`cache.ttl`	`number`	In-memory cache TTL in milliseconds
`cache.maxSize`	`number`	Max entries in the in-memory cache
`storage`	`StorageBackend`	Optional storage backend for prepared search ID persistence

The SDK does not select a storage backend automatically. Pass storage: localStorage, storage: sessionStorage, or a custom backend when you need prepared search IDs to survive navigation.

Storage backends

A storage backend is any object matching a subset of the Storage interface:

interface StorageBackend {
  getItem(key: string): string | null
  setItem(key: string, value: string): void
  removeItem(key: string): void
  clear(): void
}

Browser storage

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

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

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

Node.js (memory store)

For SSR or build scripts, pass an in-memory store:

const memoryStore = new Map<string, string>()

const nodeStorage: StorageBackend = {
  getItem: (key) => memoryStore.get(key) ?? null,
  setItem: (key, value) => memoryStore.set(key, value),
  removeItem: (key) => memoryStore.delete(key),
  clear: () => memoryStore.clear(),
}

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

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

sessionStorage

Use sessionStorage when you want prepared search IDs scoped to the current tab. The SDK still keeps controller responses in memory only:

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

Cache invalidation

The SDK does not expose a public cache invalidation API. To clear cached data, reset the SDK singleton or dispose individual controllers:

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

// Clear the current SDK instance and its in-memory cache
resetSDK()

For the most common case, changing controller parameters (for example, a new page or filter) naturally produces a new cache key.

Search cache

The search controller uses the prepare endpoint to cache expensive work. get() automatically prepares the query when needed and retries a 425 response until results are ready.

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

// Prepare caches intent analysis and query expansions
await search.prepare()

// Multiple get() calls reuse the prepare cache
await search.get({ pagination: { page: 1 } })
await search.get({ pagination: { page: 2 } })

The prepare() call returns { search_id } for observability. Reuse is automatic within the page from memory, and across pages when you configure storage. Prepared search ID entries expire after five minutes by default.

const { data: prepareData, error } = await search.prepare()

if (error) {
  console.error('Prepare failed:', error.message)
} else {
  console.log(prepareData?.search_id)
}

Custom fetch

The SDK uses the global fetch by default. Provide a custom implementation via the fetch option for SSR runtimes, testing, or environments where fetch is unavailable or blocked:

import type { FetchFn } from '@commerce-blocks/sdk'

type FetchFn = typeof globalThis.fetch

xhrFetch (browser fallback)

xhrFetch is an XMLHttpRequest-based fetch shipped with the SDK. Use it when ad blockers, browser extensions, or restrictive network policies intercept fetch calls:

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

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

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

Custom fetch

You can pass any function matching the FetchFn signature. Common uses:

SSR / Node: inject a Node-compatible fetch on older runtimes.
Testing: stub responses without intercepting global fetch.
Instrumentation: add tracing or auth headers around the request.

const tracedFetch: FetchFn = async (url, init) => {
  const start = performance.now()
  try {
    return await fetch(url, init)
  } finally {
    console.log(`[layers] ${init?.method ?? 'GET'} ${url} (${performance.now() - start}ms)`)
  }
}

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

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

The SDK handles abort signals and error classification on top of whatever fetch returns. Your adapter only needs to issue the request and return a Response.

Overview

SDK Reference

SDK Guides

Changelog & Upgrades

AI Enablement

Request deduplication

Cache configuration

Storage backends

Browser storage

Node.js (memory store)

sessionStorage

Cache invalidation

Search cache

Custom fetch

xhrFetch (browser fallback)

Custom fetch

Next steps

Performance

Best practices

​Request deduplication

​Cache configuration

​Storage backends

​Browser storage

​Node.js (memory store)

​sessionStorage

​Cache invalidation

​Search cache

​Custom fetch

​xhrFetch (browser fallback)

​Custom fetch

​Next steps

Performance

Best practices

Request deduplication

Cache configuration

Storage backends

Browser storage

Node.js (memory store)

sessionStorage

Cache invalidation

Search cache

Custom fetch

xhrFetch (browser fallback)

Custom fetch

Next steps