Cache and storage

The SDK uses an internal in-memory LRU cache with TTL eviction. Cache configuration is passed at initialization:

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 and storage in SdkConfig.

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 cache persistence (defaults to `localStorage` in the browser)

The SDK persists cache values to the configured storage backend when available. In the browser, localStorage is used automatically. Pass a custom StorageBackend if you need a different store shape, prefix, or runtime (for example, Node.js, sessionStorage, or an HTTP service).

StorageBackend

A storage backend 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
}

In the browser, localStorage satisfies this interface directly:

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 and optional storage persistence
Request deduplication: In-flight requests are deduplicated automatically

Overview

SDK Reference

SDK Guides

Changelog & Upgrades

AI Enablement

Cache and storage