Rendering blocks with the SDK

Overview

This is the SDK equivalent of Rendering blocks in Liquid. The shape of the section is the same: one Liquid section, one merchandiser-facing block-picker setting. The SDK’s blocks() controller does the HTTP call, deduplicates in-flight requests, caches results in localStorage, and exposes the products on reactive state. You do not need to handle cart context, click feedback, or cross-block product deduplication. The Layers theme app extension handles those for every Blocks request on the storefront. Use this version when you have already installed @commerce-blocks/sdk in your theme. For a no-dependencies version, see the Liquid + Fetch guide.

Prerequisites

The Layers Shopify app installed and the theme app extension enabled in Online Store → Themes → Customize → App embeds.
The SDK installed and initialized in your theme. See SDK installation.

The section

sections/layers-recommendations.liquid is the same Liquid scaffold as the Fetch version: a section with a block-picker setting and a single placeholder element carrying the selected block ID.

{% assign selected_block_id = section.settings.block_id %}

{% if selected_block_id != blank %}
  <section
    class="layers-recommendations"
    data-block-id="{{ selected_block_id }}"
    data-anchor-id="{% if template == 'product' %}{{ product.id }}{% elsif template == 'collection' %}{{ collection.handle }}{% endif %}"
  >
    {% if section.settings.heading != blank %}
      <h2>{{ section.settings.heading }}</h2>
    {% endif %}
    <ol class="layers-recommendations__products" data-loading="true"></ol>
  </section>
{% endif %}

{% schema %}
{
  "name": "Layers Recommendations",
  "settings": [
    {
      "type": "text",
      "id": "heading",
      "label": "Heading",
      "default": "You may also like"
    },
    {
      "type": "select",
      "id": "block_id",
      "label": "Block",
      "info": "Choose a Layers recommendation block.",
      "options": [
        { "value": "", "label": "Select a block" }
      ]
    }
  ],
  "presets": [{ "name": "Layers Recommendations" }]
}
{% endschema %}

The select options are populated from block metaobjects. See the Fetch guide for the pattern that mirrors metaobjects into the dropdown so merchandisers pick by name instead of pasting a ULID.

Hydrating the section

For each rendered section, create an sdk.blocks() controller with the selected block ID and the page anchor. Subscribe to the state and render on data changes.

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

const { data: sdk, error: sdkError } = getSDK()
if (sdkError) {
  console.error('SDK not initialized:', sdkError.message)
}

function hydrate(section) {
  const blockId = section.dataset.blockId
  const anchorId = section.dataset.anchorId || undefined
  const list = section.querySelector('.layers-recommendations__products')

  const blocks = sdk.blocks({ blockId, anchorId })

  blocks.subscribe(({ data, error }) => {
    if (error || (data && !data.products.length)) {
      section.hidden = true
      return
    }
    if (data) renderProducts(list, data.products)
  })

  blocks.get({ pagination: { resultsPerPage: 12 } })
}

document.querySelectorAll('.layers-recommendations').forEach(hydrate)

function renderProducts(list, products) {
  list.removeAttribute('data-loading')
  list.innerHTML = products
    .map(
      (p) => `
        <li>
          <a href="/products/${p.handle}">
            <img src="${p.featuredMedia?.url ?? ''}" alt="" />
            <h3>${p.title}</h3>
            <span>${p.priceRange?.min?.formatted ?? ''}</span>
          </a>
        </li>
      `,
    )
    .join('')
}

That is the whole integration. Multiple sections on the same page each get their own controller, run independently, and reuse the SDK’s cache and dedup machinery.

What the app embed handles for you

When the Layers theme app extension is enabled, the storefront-side embed augments every Blocks request, including the SDK’s, so you do not have to:

Cart context: current cart line items are sent automatically; cart-anchored blocks work without you reading /cart.js.
Product deduplication: products rendered earlier on the page are excluded from later blocks automatically.
Click attribution and feedback: the embed listens for clicks on rendered cards and submits feedback to keep ranking models fresh.
Identity: the storefront pixel manages deviceId and sessionId.

Your section only renders the placeholder and creates a controller. Everything else is managed for you.

Anchors

sdk.blocks({ blockId, anchorId }) resolves the right value based on template:

Template	`anchorId`
`product`	`{{ product.id }}`
`collection`	`{{ collection.handle }}`
Anything else	omitted (cart-anchored and global blocks resolve without one)

Both numeric IDs and Shopify GIDs are accepted on product anchors; both IDs and handles are accepted on collection anchors.

Why the SDK over Fetch

Concern	Fetch version	SDK version
Driving the request	`fetch` to `/blocks/{id}/products`	`blocks.get()`
Re-renders	DIY DOM updates	`subscribe()` callback
Caching across nav	DIY	Restored from `localStorage`
Multiple blocks per page	Manual orchestration	Independent controllers, SDK dedupes identical requests

Cart context, dedup, and attribution behavior is identical between the two: the theme app extension does that work either way.

Troubleshooting

The section renders but the grid stays empty. The block fell through its fallback chain. Review fallback configuration in the dashboard. Block-picker dropdown is empty. Confirm block metaobjects are visible under Content → Metaobjects in Shopify admin, and that you have populated the section setting from those metaobjects (see the Fetch guide for the pattern). Cart-anchored blocks do not refresh on cart changes. The theme app extension re-runs cart-anchored blocks. Confirm it is enabled under Online Store → Themes → Customize → App embeds.

Liquid Integration

Liquid + Fetch guides

Liquid + SDK guides

Rendering blocks with the SDK

Overview

Prerequisites

The section

Hydrating the section

What the app embed handles for you

Anchors

Why the SDK over Fetch

Troubleshooting

See also

​Overview

​Prerequisites

​The section

​Hydrating the section

​What the app embed handles for you

​Anchors

​Why the SDK over Fetch

​Troubleshooting

​See also

Overview

Prerequisites

The section

Hydrating the section

What the app embed handles for you

Anchors

Why the SDK over Fetch

Troubleshooting

See also