Upgrade guide: v1 to v2

Documentation Index

Fetch the complete documentation index at: https://docs.uselayers.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

​

Install

npm install @commerce-blocks/sdk@^2.0.0

​

Initialization

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

const { data: sdk } = createSdk({
  token: 'your-token',
  sorts: [{ name: 'Featured', code: 'featured' }],
  facets: [{ name: 'Color', code: 'options.color' }],
  enableStorefront: true,
  storefrontApiVersion: '2024-01',
  currencyCode: 'USD',
  cacheMaxEntries: 100,
  cacheTtl: 60000,
  storageAdapter: myAdapter,
  extendProduct: ({ raw }) => ({ rating: raw.calculated?.rating ?? 0 }),
  transformFilters: (filters) => filters,
  filterMap: { color: 'options.color' },
  extendCollection: (result, raw) => result,
  extendSearch: (result, raw) => result,
  extendBlock: (result, raw) => result,
  restoreFromStorage: true,
})

​

Config property renames

​

Removed config options

• enableStorefront
• storefrontApiVersion
• productMetafields / variantMetafields / collectionMetafields / pageMetafields
• options
• cacheMaxProducts

​

Storefront API removal

• Remove any @shopify/storefront-api-client dependency
• The storefront() method no longer exists on the client
• Collection metadata (title, description, image) is now fetched via includeMeta: true on collection.execute() rather than from the Storefront API
• Product metafields are available through the metafields property on the Product type, sourced from Layers

​

Controllers

​

All controllers now have subscribe()

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

const unsubscribe = collection.subscribe(({ data, error, isFetching }) => {
  if (data) render(data.products)
})

​

Collection

const collection = sdk.collection({
  handle: 'shirts',
  defaultSort: 'featured',
})

await collection.execute({
  sortOrderCode: 'price_asc',
  page: 2,
  dynamicLinking: { campaign: 'summer' },
  transformBody: (body) => body,
})

​

Search

const search = sdk.search()

await search.execute({
  query: 'ring',
  page: 1,
  limit: 20,
  dynamicLinking: { campaign: 'sale' },
})

​

Autocomplete renamed to suggest

const ac = sdk.autocomplete({ debounceMs: 300 })

ac.execute(query)
// ac.state is ReadonlySignal<QueryState<PredictiveSearchResponse>>

ac.dispose()

​

Blocks

const blocks = sdk.blocks({
  blockId: 'block-abc',
  anchorId: '12345',
  // or anchorHandle: 'gold-necklace'
})

await blocks.execute({
  discountEntitlements: [{ entitled: { all: true }, discount: { type: 'PERCENTAGE', value: 10 } }],
  dynamicLinking: { campaign: 'vip' },
})

​

Image search

const upload = sdk.uploadImage({ image: file })
// returns ReadonlySignal<QueryState<UploadImageResult>>

const results = sdk.imageSearch({ imageId: 'img-123', limit: 10 })
// returns ReadonlySignal<QueryState<SearchResult>>

​

Product type changes

​

Key differences

• Shallow by default: Products include only the matched variant in variants. Enable full variants with flags: { variants: true } in createClient.
• selectedOptions is now on the product itself (the matched variant’s options)
• breakoutOptions replaces the previous breakout variant handling
• options are now RichProductOption[] with code and optional swatch
• category field added with taxonomy data
• metafields is a nested Record<string, Record<string, unknown>> (namespace/key structure)
• combinedListingParentProductId and combinedListingRole added for combined listings

​

Removed product fields

• descriptionHtml
• onlineStoreUrl
• seo
• publishedAt
• collections (use includeMeta on collection queries instead)

​

Error handling

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

if (result.error) {
  // error._tag: 'NetworkError' | 'ApiError' | 'ValidationError' | 'ConfigError'
}

​

Cache and store

const { store } = sdk
// store.queries, store.collections, etc.

​

New in v2

• searchContent controller for searching articles and blog content
• createProductCard reactive controller for building product cards with variant selection, option availability, and pricing signals
• subscribe() on all controllers for framework-agnostic reactivity
• Request deduplication via the built-in RequestCoordinator
• temporary flag on search for one-shot query overrides that don’t persist
• prepare() on search for warming the API with a searchId before executing
• Shallow products for significantly smaller payloads on listing pages

​

Type renames