Cache and storage

The SDK keeps controller responses in an internal in-memory LRU cache with TTL eviction for the life of the page. Nothing in this cache survives a page load. Configure storage separately when you want to persist prepared search IDs across pages:

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

The public cache object exposed in v2 has been removed. Cache behavior is controlled through cache in SdkConfig. The optional storage value is used only by the search prepare store.

Cache configuration

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

Controller responses stay in memory only. The SDK uses the configured StorageBackend to persist prepared search IDs so a later page can reuse them. Pass a backend such as localStorage, sessionStorage, or a custom implementation when you need cross-page prepare reuse.

StorageBackend

A storage backend persists prepared search IDs. It is any object matching this subset of the Storage interface:

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

Pass localStorage or sessionStorage when you want prepared search IDs to survive navigation within the browser:

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

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

For Node.js or SSR, pass an object that wraps your 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,
})

Custom fetch

The SDK uses the global fetch by default. You can provide a custom fetch implementation for SSR, testing, or environments where fetch is not available:

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

type FetchFn = typeof globalThis.fetch

The SDK also exports xhrFetch, an XMLHttpRequest-based fetch alternative for environments where fetch is blocked by ad blockers or browser extensions:

import { xhrFetch, createSDK } 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)
}

Singleton access

After initialization, access the SDK anywhere:

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

if (isInitialized()) {
  const { data: sdk, error } = getSDK()
  if (error) {
    console.error('SDK not initialized:', error.message)
  } else if (sdk) {
    // Use sdk
  }
}

// To reset the singleton state and clear the current SDK instance:
resetSDK()

Technical details

Runtime: Browser (ESM) and Node.js with a custom fetch and storage
TypeScript: Full type definitions included
Dependencies: None
Bundle: Tree-shakeable ES modules
Caching: In-memory LRU cache with TTL for controller responses
Request deduplication: In-flight requests with the same parameters are deduplicated
Prepared search IDs: Optional storage backend with a five-minute default TTL

Overview

SDK Reference

SDK Guides

Changelog & Upgrades

AI Enablement

Cache and storage