Caching

The SDK automatically caches requests to minimize API calls and improve performance.

Request deduplication

When multiple components request the same data, the SDK automatically deduplicates requests:

const collection1 = client.collection({ handle: 'shirts' })
const collection2 = client.collection({ handle: 'shirts' })

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

// Only ONE network request is made

Local storage restoration

Cached results are restored from local storage on back navigation:

// Initial page load
const collection = client.collection({ handle: 'shirts' })
await collection.execute() // Makes API call, caches result

// User navigates away and returns via back button
// Cache is restored from localStorage - no API call needed

Disable auto-restore if needed:

const { data: client } = createClient({
  token: 'your-token',
  sorts: [{ name: 'Featured', code: 'featured' }],
  facets: [{ name: 'Color', code: 'options.color' }],
  restoreCache: false,
})

Cache invalidation

Invalidate cached queries by pattern:

const { cache } = client

// Invalidate all browse queries
cache.invalidate('browse')

// Invalidate specific search
cache.invalidate('search:ring')

// Clear all cache
cache.clear()

Search cache

The prepare endpoint caches expensive operations (embeddings, query expansions):

const search = client.search()

await search.prepare({ query: 'ring' })

// Multiple executes reuse the prepare cache
await search.execute({ query: 'ring', page: 1 })
await search.execute({ query: 'ring', page: 2 })

When using search_id, the server maintains the cache for 15 minutes:

const prepareResult = await search.prepare({ query: 'ring' })
const searchId = prepareResult.data?.searchId

await search.execute({ 
  query: 'ring',
  searchId,
})

Storage adapters

Cache persistence is pluggable via a StorageAdapter. The SDK ships two adapters and accepts any custom implementation, so the cache survives reloads in the browser, page navigations in SSR frameworks, or process restarts in Node.

Adapter	Environment	Import
`localStorageAdapter(key)`	Browser (default)	`@commerce-blocks/sdk`
`fileStorage(path, fs)`	Node.js / build scripts	`@commerce-blocks/sdk`
Custom `StorageAdapter`	Any (sessionStorage, IndexedDB, Redis, etc.)	Bring your own

Browser (localStorage)

localStorage is used automatically when the SDK runs in a browser. Pass an explicit adapter only if you want to customize the storage key:

import { createClient, localStorageAdapter } from '@commerce-blocks/sdk'

const { data: client } = createClient({
  token: 'your-token',
  sorts: [{ name: 'Featured', code: 'featured' }],
  facets: [{ name: 'Color', code: 'options.color' }],
  storage: localStorageAdapter('shop:cache:v1'),
})

localStorageAdapter returns null in environments without window.localStorage (e.g. SSR), so the SDK silently falls back to in-memory caching — safe to use in isomorphic code.

Node.js (file system)

Use fileStorage to persist the cache to disk for build scripts, server-rendered pages, or long-running Node processes:

import fs from 'node:fs'
import { createClient, fileStorage } from '@commerce-blocks/sdk'

const { data: client } = createClient({
  token: process.env.LAYERS_TOKEN!,
  sorts: [{ name: 'Featured', code: 'featured' }],
  facets: [{ name: 'Color', code: 'options.color' }],
  storage: fileStorage('./.cache/layers.json', fs),
})

The adapter takes a minimal FileSystem interface (readFileSync, writeFileSync, unlinkSync), so you can substitute a mock in tests or wrap an alternative file system.

Custom adapter

Implement StorageAdapter to back the cache with anything else — sessionStorage, IndexedDB, Redis, Cloudflare KV, an HTTP service, etc.

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

const sessionAdapter: StorageAdapter = {
  read: () => sessionStorage.getItem('layers:cache'),
  write: (data) => sessionStorage.setItem('layers:cache', data),
  remove: () => sessionStorage.removeItem('layers:cache'),
}

const { data: client } = createClient({
  token: 'your-token',
  sorts: [{ name: 'Featured', code: 'featured' }],
  facets: [{ name: 'Color', code: 'options.color' }],
  storage: sessionAdapter,
})

All three adapter methods are synchronous and operate on a single serialized JSON string. Wrap async backends in a sync queue or memoize the latest snapshot if you need IndexedDB or remote storage. See Cache, storage, and signals for the full interface reference.

Fetch adapter

The SDK calls 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 { CustomFetch } from '@commerce-blocks/sdk'

type CustomFetch = (url: string, init?: RequestInit) => Promise<Response>

xhrFetch (browser fallback)

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

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

const { data: client } = createClient({
  token: 'your-token',
  sorts: [{ name: 'Featured', code: 'featured' }],
  facets: [{ name: 'Color', code: 'options.color' }],
  fetch: xhrFetch,
})

Custom fetch

Any function matching the CustomFetch signature can be passed. Common uses:

SSR / Node: inject a Node-compatible fetch (e.g. undici, node-fetch) on older runtimes.
Testing: stub responses without intercepting global fetch.
Instrumentation: add tracing, retries, or auth headers around the request.

const tracedFetch: CustomFetch = 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: client } = createClient({
  token: 'your-token',
  sorts: [{ name: 'Featured', code: 'featured' }],
  facets: [{ name: 'Color', code: 'options.color' }],
  fetch: tracedFetch,
})

The SDK handles retries, 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

Local storage restoration

Cache invalidation

Search cache

Storage adapters

Browser (localStorage)

Node.js (file system)

Custom adapter

Fetch adapter

xhrFetch (browser fallback)

Custom fetch

Next steps

Performance

Best Practices

​Request deduplication

​Local storage restoration

​Cache invalidation

​Search cache

​Storage adapters

​Browser (localStorage)

​Node.js (file system)

​Custom adapter

​Fetch adapter

​xhrFetch (browser fallback)

​Custom fetch

​Next steps

Performance

Best Practices

Request deduplication

Local storage restoration

Cache invalidation

Search cache

Storage adapters

Browser (localStorage)

Node.js (file system)

Custom adapter

Fetch adapter

xhrFetch (browser fallback)

Custom fetch

Next steps