Skip to main content
The Layers SDK (@protonagency/commerce-blocks-sdk) is a TypeScript SDK that provides unified APIs for integrating Layers’ AI-powered search and discovery capabilities into your e-commerce applications. It handles data fetching, caching, and reactive state management, allowing you to build rich commerce experiences with minimal boilerplate.

​
Key Features

The SDK provides a comprehensive set of tools for building commerce experiences:

Layers API Integration

Full access to Layers’ search, browse, similar products, and image search APIs with built-in error handling.

Reactive State Management

Built-in Preact Signals integration for reactive UI updates with automatic caching and request deduplication.

Web Components

Declarative custom elements for data fetching that work with any framework or vanilla JavaScript.

Shopify Integration

Automatic product enrichment by combining Layers search data with fresh Shopify Storefront API data.

​
Architecture

The SDK is designed as a layered system that separates concerns between data fetching, state management, and UI rendering: 
@protonagency/commerce-blocks-sdk (data, caching, signals)
  └─ @protonagency/commerce-blocks-widget (pre-built UI components)
The SDK handles all data fetching, caching, and reactivity. The optional Widget library provides pre-built Preact components for common use cases that you can drop into any storefront.

​
Available APIs

The SDK provides access to all Layers storefront APIs:
APIDescription
BrowseBrowse and filter products within merchandised collections
SearchFull-text semantic search with typo tolerance and query understanding
Similar ProductsFind products visually and semantically similar to a reference product
Predictive SearchReal-time autocomplete and search suggestions
Image SearchSearch for products using uploaded images

​
Usage Patterns

The SDK supports two primary usage patterns depending on your needs:

​
Direct API Access

For simple use cases or server-side rendering, use the factory functions to create API clients: 
import { useLayers } from '@protonagency/commerce-blocks-sdk';

const api = useLayers({
  apiToken: 'your-layers-token',
});

const result = await api.browse({
  collectionHandle: 'summer-sale',
  sortOrderCode: 'best_selling',
  pagination: { page: 1, limit: 20 },
});

​
App Module with Reactive State

For client-side applications, initialize the SDK to enable reactive caching and web components: 
import { initialize } from '@protonagency/commerce-blocks-sdk';

const app = initialize({
  layers: {
    accessToken: 'your-layers-token',
    store: {
      name: 'My Store',
      shopDomain: 'my-store.myshopify.com',
    },
    shopOptions: {
      metafieldNamespaces: [],
      attributes: [
        { name: 'Color', code: 'color', usedIn: ['Filter', 'Grouping'] },
        { name: 'Size', code: 'size', usedIn: ['Filter'] },
      ],
      swatches: [
        { value: 'red', swatch: { color: '#E31837' } },
        { value: 'navy', swatch: { color: '#001F5B' } },
      ],
    },
  },
  storefront: {
    shop: 'my-store.myshopify.com',
    accessToken: 'your-shopify-storefront-token',
  },
});
The app module provides reactive methods that return Preact Signals, localStorage persistence with LRU eviction, request deduplication, and automatic product enrichment.

​
Next Steps

Installation

Learn how to install and configure the SDK in your project.

API Reference

Explore the complete API reference for all SDK methods.

Web Components

Use declarative web components for data fetching.

Widgets

Build UIs faster with pre-built widget components.