Caching

The SDK automatically caches requests in memory to minimize API calls and improve performance. Cache persistence is optional and backed by a StorageBackend such as localStorage.

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 cache persistence

In the browser, localStorage is used automatically when a StorageBackend is available. Pass storage: localStorage or a custom object.

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 (localStorage)

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

Swap localStorage for sessionStorage to keep cached data only while the tab is open:

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 all cached data
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 } })

When you pass a searchId, the server maintains the prepared state for a short window:

const { data: prepareData } = await search.prepare()
const searchId = prepareData?.searchId

await search.get({ searchId })

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

Any function matching the FetchFn signature can be passed. 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 (localStorage)

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 (localStorage)

​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 (localStorage)

Node.js (memory store)

sessionStorage

Cache invalidation

Search cache

Custom fetch

xhrFetch (browser fallback)

Custom fetch

Next steps