Utilities compartilhadas de commerce

@decocms/apps-* expõe utilities neutras à plataforma — tipos, helpers de formatação e componentes — em subpaths sob commerce/. Use sempre que possível: você fica trocando de provider para sempre.

Tipos

import type {
  Product,
  ProductDetailsPage,
  ProductListingPage,
  BreadcrumbList,
  Offer,
  AggregateOffer,
  Cart,
  CartItem,
} from "@decocms/apps-commerce/types";

Alinhados ao schema.org. VTEX e Shopify mapeiam para essas formas em loaders.

useOffer

import { useOffer } from "@decocms/apps-commerce/sdk/useOffer";
 
const offer = useOffer(product.offers);
// → { price, listPrice, seller, availability, hasDrawnOutOfStockLabel }

Hook que extrai o "main offer" de um produto — o que tem o melhor preço para o usuário corrente. Comportamento embutido:

• Pega o seller default (ou usa ?seller=... da URL).
• Calcula porcentagem de desconto.
• Sinaliza disponibilidade (InStock, OutOfStock).
• Lida com listas de oferta vazias com tipos seguros.

Usado em todo PDP card e prateleira de produto.

formatPrice

import { formatPrice } from "@decocms/apps-commerce/sdk/formatPrice";
 
formatPrice(1234.56, "BRL", "pt-BR");
// → "R$ 1.234,56"

Wrapper em volta de Intl.NumberFormat com defaults de currency / locale via env ou config do site.

useVariantPossibilities

import { useVariantPossibilities } from "@decocms/apps-commerce/sdk/useVariantPossibilities";
 
const variants = useVariantPossibilities(product);
// → mapa de eixo → [{ value, link, available }]

Para PDPs com múltiplas variantes (cor, tamanho), produz um mapa estruturado para renderizar UI de seletor. Lida com:

• Variantes indisponíveis (mostradas riscadas).
• Configuração com SKU pré-selecionado (?skuId=...).
• Geração da URL do próximo variant via slug.

Componente Image

import { Image, registerImageCdnDomain } from "@decocms/blocks/hooks";
 
<Image
  src="https://..."
  alt="Tênis"
  width={400}
  height={400}
  loading="lazy"
  decoding="async"
/>

Wrapper em volta de <img> que automaticamente:

• Adiciona loading="lazy" exceto na primeira imagem da página (heurística LCP).
• Roteia através do CDN de imagem de ~/cdn.decocms.com/ para sizing responsivo.
• Aplica decoding="async".
• Aceita srcSet para imagens responsivas.

Componente Picture

import { Picture, Source } from "@decocms/blocks/hooks";
 
<Picture src="https://..." alt="Tênis">
  <Source media="(max-width: 768px)" src="https://.../mobile.jpg" />
  <Source media="(min-width: 769px)" src="https://.../desktop.jpg" />
</Picture>

<picture> com fallback. Para arte responsiva (mobile vs desktop usando crops diferentes).

JsonLd

import { ProductJsonLd, BreadcrumbJsonLd, PLPJsonLd } from "@decocms/blocks/hooks";
 
<ProductJsonLd product={product} url={pageUrl} />
<BreadcrumbJsonLd breadcrumbs={breadcrumbList} />
<PLPJsonLd page={productListingPage} />

Renderiza <script type="application/ld+json"> com payload schema.org. Use em PDP e PLP para SEO.

Analytics

import {
  sendEvent,
  trackEvent,
  initAnalytics,
} from "@decocms/apps-commerce/sdk/analytics";

Wrapper estilo GTM. Empurra eventos para window.dataLayer:

sendEvent({
  name: "view_item",
  params: { item_id: product.id, item_name: product.name },
});

trackEvent é o equivalente server-side; loga via instrumented fetch para sua coleta de eventos.

initAnalytics aceita ID GTM, ID Meta Pixel etc. e instala os scripts. Tipicamente chamado do shell do root layout.

URL utilities

import {
  getISCookies,
  getRegionId,
  buildProductUrl,
} from "@decocms/apps-commerce/sdk/url";

Helpers para tarefas comuns de URL específicas de commerce — extrair regionId de cookies, construir URLs de PDP a partir de slugs.

Veja também

• Visão geral de commerce
• VTEX inline loaders
• VTEX hooks
• Reference de exports de commerce