Commerce types and utilities

@decocms/apps-commerce is the platform-neutral layer under every commerce app. It doesn't talk to any backend. Instead it defines the shapes they all return (a product, a product page, a listing page, a cart), so a section written against these types works whether the data came from VTEX, Shopify or Wake. It also holds the Cart v2 contract, the app contract types, and a handful of helpers for prices, links and analytics.

It ships no UI components. Images, pictures and JSON-LD components live in @decocms/blocks/hooks (see Images, scripts and UI helpers).

bun add @decocms/apps-commerce

The shared vocabulary

The types follow schema.org, the same vocabulary search engines read, so the data a loader returns can also be rendered as structured data. Import them from @decocms/apps-commerce/types:

import type { Product } from "@decocms/apps-commerce/types";
 
export interface Props {
  /** @title Products */
  products: Product[] | null;
}
 
export default function ProductShelf({ products }: Props) {
  return (
    <ul>
      {products?.map((p) => (
        <li key={p.productID}>
          <img src={p.image?.[0]?.url} alt={p.name} width={200} height={200} />
          <a href={p.url}>{p.name}</a>
          <span>{p.offers?.lowPrice}</span>
        </li>
      ))}
    </ul>
  );
}

The types you'll use most:

Money is always in major units: 19.9 means 19.90 in the store's currency, never 1990 cents.

Analytics types and mappers

The package also defines the GA4 event vocabulary: AnalyticsItem and the event types (AddToCartEvent, ViewItemEvent, ViewItemListEvent, SelectItemEvent, BeginCheckoutEvent and the rest), grouped in the AnalyticsEvent union. A deco event carries the page's active flags.

To turn a Product into an AnalyticsItem, there are two mappers with the same name in different places. Neither reads the price from the product: you pass it in, usually from useOffer. They also don't produce identical output:

In both, discount is listPrice - price when you pass both options. Pick one mapper and use it everywhere, so the same product reports the same fields on every event. Both accept a breadcrumbList, which gives the most reliable category fields; without it they fall back to the product's category string.

import { mapProductToAnalyticsItem } from "@decocms/apps-commerce/sdk/analytics";
import { useOffer } from "@decocms/apps-commerce/sdk/useOffer";
import type { Product } from "@decocms/apps-commerce/types";
 
export function toItem(product: Product, index: number) {
  const { price, listPrice } = useOffer(product.offers);
  return mapProductToAnalyticsItem({
    product,
    index,
    quantity: 1,
    lowPrice: price,
    price,
    listPrice,
  });
}

Cart v2: sections and projection

Cart v2 splits every cart operation into two independent choices, so a page only pays for the data it shows:

• sections: what to ask the platform to compute. On VTEX these map to the order form's sections (items, totalizers, shippingData, paymentData and so on).
• projection: what the server sends back to the browser.

Three section presets cover the usual cases: SECTIONS_MINIMAL (items, totals, messages), SECTIONS_DRAWER (what a drawer renders, including shipping and sellers) and SECTIONS_FULL. defaultSectionsFor(projection) picks the matching preset when you pass only a projection. The types and presets are exported from @decocms/apps-commerce/types/cart, and re-exported from @decocms/apps-commerce/types.

VTEX is the first platform to implement Cart v2; see VTEX.

Helpers

import { formatPrice } from "@decocms/apps-commerce/sdk/formatPrice";
import { relative } from "@decocms/apps-commerce/sdk/url";
 
formatPrice(99, "USD", "en-US"); // "$99.00"
relative("https://www.example.com/p/shoe?idsku=1&color=red", { stripSearchParams: ["idsku"] }); // "/p/shoe?color=red"

App contract types

The types for writing an app live here too, so apps don't depend on the framework packages:

• @decocms/apps-commerce/app-types: AppDefinition, AppManifest, AppMiddleware, AppModContract, ResolveSecretFn.
• @decocms/apps-commerce/registry: AppRegistryEntry and AppRegistry, the shape of each app's *_REGISTRY_ENTRY.
• @decocms/apps-commerce/resolve: resolveApps(apps), which merges several app definitions into one manifest and chains their middleware (the first app runs outermost).
• @decocms/apps-commerce/manifest-utils: extractHandlers(manifest), which flattens a manifest into one function per key.

Apps explains how the framework uses them.

Related

• Apps: installing and configuring apps.
• VTEX: the reference implementation of these types and of Cart v2.
• SEO: turning these types into structured data.