Skip to main content
The Layers SDK and Widget library are currently in beta. Follow these steps to get access and install them in your project.

​
Getting Access

The SDK and Widget library are currently in beta. To request access, contact Layers Support and they will provide you with the necessary credentials to install the packages.

​
Installation

Once you have received your access credentials from Layers Support, you can install the packages: 
npm install @protonagency/commerce-blocks-sdk

​
Peer Dependencies

The SDK requires the following peer dependencies for reactive state management: 
npm install preact @preact/signals

​
Quick Start

​
Direct API Usage

For simple API calls without reactive state: 
import { useLayers } from '@protonagency/commerce-blocks-sdk';

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

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

// Handle errors using the Result pattern
if (result.error) {
  console.error(result.error._tag, result.error.message);
  return;
}

console.log(result.data.results);

​
App Module Initialization

For client-side applications with reactive state and caching: 
import { initialize, getSdk, isInitialized } 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', // Optional
  },
});

// Check if initialized
if (isInitialized()) {
  const sdk = getSdk();
}

​
Configuration Options

​
Layers API Configuration

​
layers.accessToken
string
required
Your Layers API token from the dashboard.
​
layers.store.name
string
required
Store name for display purposes.
​
layers.store.shopDomain
string
required
Your Shopify store domain (e.g., my-store.myshopify.com).
​
layers.shopOptions.metafieldNamespaces
string[]
required
Metafield namespaces to include. Can be an empty array.
​
layers.shopOptions.attributes
array
required
Product attributes with name, code, and usedIn array specifying where the attribute is used (Filter, Grouping).
​
layers.shopOptions.swatches
array
required
Brand color swatches with value and swatch object containing either color (hex) or imageUrl.
​
layers.baseUrl
string
Custom Layers API URL. Defaults to https://app.uselayers.com.

​
Shopify Storefront Configuration

​
storefront.shop
string
required
Your Shopify store domain.
​
storefront.accessToken
string
Shopify Storefront API access token. Optional if using Layers-only mode.
​
storefront.apiVersion
string
default:"2025-10"
Shopify Storefront API version.

​
App Options

​
currencyCode
string
default:"USD"
Currency code for Layers fallback pricing.
​
options.layersOnly
boolean
default:"false"
Skip Shopify enrichment and use Layers data only.
​
options.debug
boolean
default:"false"
Enable debug mode with $CB console helper.
​
options.persist
boolean
default:"true"
Enable localStorage persistence for caching.
​
options.cache.maxProducts
number
default:"100"
Maximum product entries to cache.
​
options.cache.maxEntries
number
default:"50"
Maximum entries per endpoint cache.
​
options.cache.debounceMs
number
default:"100"
Debounce delay for persistence writes in milliseconds.

​
Tree-Shakeable Imports

Import specific modules for smaller bundles: 
// Full SDK
import { initialize, useLayers } from '@protonagency/commerce-blocks-sdk';

// App module only
import { initialize } from '@protonagency/commerce-blocks-sdk/app';

// Layers API only
import { useLayers } from '@protonagency/commerce-blocks-sdk/api/layers';

// Utilities only
import { filter, throttle, debounce } from '@protonagency/commerce-blocks-sdk/utils';

// Web components only
import { BrowseProvider, SearchProvider } from '@protonagency/commerce-blocks-sdk/components';

​
Debug Mode

When initialized with options.debug: true, access the $CB helper in your browser console: 
$CB.help();      // Show available commands
$CB.store;       // Access reactive store
$CB.inspect();   // Log store state
$CB.clear();     // Clear cache
$CB.layersApi;   // Direct API access

​
Important Notes

All API methods return a Result type instead of throwing exceptions. Always check for result.error before accessing result.data.