Ir para o conteúdo
decodecodeveloper docs
Storefront → Templates → Commerce

VTEX — loaders & actions

Cookbook completo de loaders/* e actions/* com input/output.

Esta página é o cookbook. Toda função do @decocms/apps-vtex/loaders e @decocms/apps-vtex/actions, com sua forma esperada e quando usar.

Loaders (leitura)

vtex/loaders/intelligentSearch/productDetailsPage.ts

Devolve ProductDetailsPage para uma URL canônica de produto.

{
  slug: string;          // identificador da URL do produto
}

Devolve ProductDetailsPage | null (null se não encontrado).

vtex/loaders/intelligentSearch/productListingPage.ts

Devolve ProductListingPage para PLP de categoria ou marca.

{
  category?: string[];   // segmentos de path da categoria
  collection?: string;   // ID da coleção
  count?: number;        // produtos por página, default 24
  sort?: string;         // chave whitelisted (price:asc, release:desc etc.)
  filters?: Record<string, string>;
  page?: number;
}

Devolve ProductListingPage | null.

vtex/loaders/intelligentSearch/searchPage.ts

Devolve ProductListingPage para query de busca.

{
  query?: string;
  count?: number;
  sort?: string;
  filters?: Record<string, string>;
  page?: number;
}

vtex/loaders/intelligentSearch/productList.ts

Devolve Product[] (sem o wrap PDP/PLP). Use para shelves, related products, recently viewed.

{
  query?: string;
  count?: number;        // default 12
  sort?: string;
  ids?: string[];        // SKU ou productId
  collection?: string;
}

vtex/loaders/intelligentSearch/suggestions.ts

Sugestões de autocomplete para uma query parcial.

{ query: string }

Devolve { products: Product[]; suggestions: string[] }.

vtex/loaders/intelligentSearch/topSearches.ts

Buscas top do dia (sem props).

vtex/loaders/cart.ts

Devolve o orderForm corrente como Cart.

{}  // sem props; lê o cookie do orderForm

Devolve Cart (orderForm vazio se nenhum cookie).

vtex/loaders/user.ts

Devolve o usuário logado.

{}

Devolve User | null.

vtex/loaders/wishlist/list.ts

Devolve a wishlist do usuário.

{ count?: number }

Devolve Product[].

vtex/loaders/orders/list.ts

Lista de pedidos do usuário.

{ page?: number; perPage?: number }

Devolve { list: Order[]; pageInfo: PageInfo }.

vtex/loaders/legacy/productList.ts

Mesmo que IS productList, mas usa Catalog API legado. Use só se Intelligent Search não estiver configurado.

vtex/loaders/legacy/categoryTree.ts

Árvore de categorias para nav.

{ depth?: number }

Devolve Category[] aninhadas.

vtex/loaders/legacy/collections.ts

Lista de coleções.

{}

vtex/loaders/postalCode/regionId.ts

Resolve um CEP para regionId de VTEX (necessário para precisão de estoque/preço).

{ postalCode: string; country?: string }

Devolve { regionId: string; salesChannel: string } | null.

vtex/loaders/sellers/list.ts

Sellers ativos para o sales channel atual.

{ count?: number }

Actions (mutações)

vtex/actions/cart/addItems.ts

{ items: { id: string; quantity: number; seller?: string }[] }

Devolve Cart atualizado.

vtex/actions/cart/removeItems.ts

{ index: number }   // posição no orderForm

vtex/actions/cart/updateItems.ts

{ orderItems: { index: number; quantity: number }[] }

vtex/actions/cart/updateCoupon.ts

{ text: string }

vtex/actions/cart/updateClientPreferences.ts

{ locale?: string; optInNewsletter?: boolean }

vtex/actions/cart/updateProfile.ts

{ email: string }

vtex/actions/cart/changeRegion.ts

{ postalCode: string; country?: string }

Atualiza o orderForm com regionId.

vtex/actions/wishlist/add.ts

{ productId: string; sku?: string }

vtex/actions/wishlist/remove.ts

{ id: string }

vtex/actions/user/signIn.ts

{ email: string; password: string }

Devolve { ok: boolean; redirect?: string }.

vtex/actions/user/signUp.ts

{ email: string; firstName: string; lastName: string; password: string }

vtex/actions/user/signOut.ts

{}

vtex/actions/newsletter/subscribe.ts

{ email: string; name?: string }

Padrões

Chamada do client (preferida)

import { invoke } from "~/server/cms/invoke.gen";
 
const cart = await invoke["vtex/actions/cart/addItems.ts"]({
  items: [{ id: "12345", quantity: 1 }],
});

Tipado e cuidado pelos hooks do TanStack Query (via useCart etc.).

CMS multistep

Se o autor de conteúdo precisar configurar uma instância de loader (e.g. uma prateleira de produto na home), o CMS embrulha o __resolveType e props num block:

{
  "__resolveType": "vtex/loaders/intelligentSearch/productList.ts",
  "query": "tênis",
  "count": 12
}

Section pega o resultado como uma prop:

export interface Props {
  loader: { __resolveType: string };
}
 
export const loader = (props: Props, _req, ctx) => ctx.invoke(props.loader);
 
export default function Shelf({ products }: Props & { products: Product[] }) { /* ... */ }

Pegadinha de sort whitelist

O parâmetro sort em loaders IS é validado contra uma whitelist (price:asc, price:desc, release:desc, name:asc, score:desc etc.). Valores fora da whitelist resetam para o default do servidor.

Causas comuns: passar sort=relevancia (deveria ser score:desc) de uma migração antiga.

Veja sortwhitelist.ts para a lista exata.

Veja também