> ## 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.

# SDK overview

> Overview of the Layers SDK — an ES module library for product discovery, search, browse, and recommendations powered by the Layers API.

The Layers SDK (`@commerce-blocks/sdk`) is an ES module SDK for product discovery powered by Layers API. It provides reactive state management, built-in caching, and a unified interface for browse, search, recommendations, and image search.

## Key features

<CardGroup cols={2}>
  <Card title="Layers API Integration" icon="magnifying-glass">
    Full access to Layers' search, browse, recommendations, blocks, and image search APIs with built-in error handling.
  </Card>

  <Card title="Reactive State Management" icon="bolt">
    Framework-agnostic reactive signals for automatic UI updates with built-in caching and request deduplication.
  </Card>

  <Card title="Product Card Controller" icon="square-check">
    Reactive product card management with variant selection, availability logic, and automatic state updates.
  </Card>

  <Card title="Extensibility" icon="puzzle-piece">
    Transform products, collections, and search results with custom transforms. Map filter keys for URL-friendly parameters.
  </Card>
</CardGroup>

## Quick start

```typescript theme={null}
import { createClient } from '@commerce-blocks/sdk'

const { data: client, error } = createClient({
  token: 'your-layers-token',
  sorts: [
    { name: 'Featured', code: 'featured' },
    { name: 'Price: Low to High', code: 'price_asc' },
  ],
  facets: [
    { name: 'Color', code: 'options.color' },
    { name: 'Size', code: 'options.size' },
  ],
})

if (error) {
  console.error('Client init failed:', error.message)
} else {
  const collection = client.collection({ handle: 'shirts' })
  const result = await collection.execute()
  
  if (result.data) {
    console.log(result.data.products)
  }
  
  collection.dispose()
}
```

## Client methods

The client provides controllers for all Layers storefront APIs:

| Method                   | Description                                                         |
| ------------------------ | ------------------------------------------------------------------- |
| `client.collection()`    | Browse and filter products within merchandised collections          |
| `client.search()`        | Semantic product search with prepare/execute flow                   |
| `client.suggest()`       | Predictive search suggestions with debouncing and local caching     |
| `client.blocks()`        | Product recommendations powered by Layers blocks                    |
| `client.uploadImage()`   | Upload images for image-based search                                |
| `client.searchByImage()` | Search products using uploaded images                               |
| `client.searchContent()` | Search articles and blog content                                    |
| `createProductCard()`    | Reactive product card with variant selection and availability logic |

## Architecture

The SDK uses a controller pattern where each method returns a controller with reactive state and execute methods. All controllers support three ways to consume state:

```typescript theme={null}
import { effect, subscribe } from '@commerce-blocks/sdk'

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

// 1. Controller subscribe (no signal import needed)
const unsubscribe = collection.subscribe(({ data, error, isFetching }) => {
  if (isFetching) console.log('Loading...')
  if (error) console.error('Error:', error.message)
  if (data) console.log('Products:', data.products)
})

// 2. Standalone subscribe (works with any signal)
const unsubscribe2 = subscribe(collection.state, (state) => {
  console.log('State changed:', state)
})

// 3. Direct signal access (for custom reactivity)
effect(() => {
  const { data } = collection.state.value
  if (data) console.log('Products:', data.products)
})

// Execute queries
await collection.execute() // initial load
await collection.execute({ page: 2 }) // pagination
await collection.execute({ sort: 'price_asc' }) // change sort

// Cleanup
collection.dispose()
```

## Next steps

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/sdk/installation">
    Learn how to install and configure the SDK in your project.
  </Card>

  <Card title="API Reference" icon="book" href="/sdk/api-reference">
    Explore the complete API reference for all SDK methods.
  </Card>

  <Card title="Framework Integration" icon="puzzle-piece" href="/sdk/framework-integration">
    Patterns for React, Vue, Svelte, Lit, and vanilla JS.
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/sdk/error-handling">
    Learn how to handle errors gracefully with the Result pattern.
  </Card>
</CardGroup>