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

Visão geral da VTEX

Conecte um storefront Blocks 7.x publicado à VTEX com os módulos registrados do provedor.

O app VTEX fornece integrações de catálogo, busca, carrinho, conta e sessões no servidor, além dos hooks React suportados. Este guia é para Blocks 7.x; consulte a referência VTEX versionada para o contrato completo do runtime.

O que você precisa

Use sua conta VTEX e credenciais de API suportadas. O site implementa a UI; o app integra o provedor; o Site Editor altera a configuração salva.

Configuration block

Salve a conta e a URL pública do storefront:

.deco/blocks/deco-vtex.json
{
  "__resolveType": "deco-vtex",
  "account": "my-store",
  "publicUrl": "https://my-store.example.com",
  "locale": "pt-BR",
  "country": "BRA"
}

A autoconfiguração resolve appKey e appToken por valores criptografados ou pelas variáveis VTEX_APP_KEY / VTEX_APP_TOKEN do servidor. O par é enviado apenas quando os dois existem. country recebe um código ISO alpha-3, como BRA; salesChannel é um padrão legado descontinuado, não um substituto para o contexto por visitante.

Wiring no setup

Registre o provedor depois de carregar o decofile. Importe este módulo pelo Worker entry após ./setup:

src/setup/apps.ts
import { autoconfigApps, type AppRegistry } from "@decocms/blocks-admin/apps";
import { loadBlocks } from "@decocms/blocks/cms";
import { VTEX_REGISTRY_ENTRY } from "@decocms/apps-vtex/registry";
import * as vtexMod from "@decocms/apps-vtex/mod";
 
const APP_REGISTRY: AppRegistry = [
  { ...VTEX_REGISTRY_ENTRY, module: async () => vtexMod },
];
 
await autoconfigApps(loadBlocks(), APP_REGISTRY);

autoconfigApps recebe o mapa de blocos e um registro composto pelo site. Se usar initVtexFromBlocks(blocks), passe o mapa recebido por initPlatform; esse inicializador aceita apenas credenciais em texto.

Registrar loaders de commerce

Para loaders de produto e listagem com cache e entradas compatíveis com o CMS:

import { registerCommerceLoaders } from "@decocms/blocks/cms";
import { createVtexCommerceLoaders } from "@decocms/apps-vtex/commerceLoaders";
 
registerCommerceLoaders(createVtexCommerceLoaders());

Instrumentar o provedor

Configure o fetch resiliente e instrumentado uma vez no setup do servidor:

import { setVtexFetch, createVtexFetch } from "@decocms/apps-vtex";
 
setVtexFetch(createVtexFetch());

Middleware

No TanStack, conecte cache por segmento, proxy de checkout e proxy de sitemap pelo Worker entry. Use o exemplo de wiring do Worker, sem tratar helpers do provedor como factories de middleware TanStack. O binding Next.js possui outro contrato de requisição.

O que você recebe

Loaders e actions registrados, configuração do app, hooks de carrinho/usuário/wishlist e comportamento de requisição específico do provedor. O código precisa registrá-los antes de expor seus schemas no Site Editor. Cart v2 é o nome do contrato de carrinho, independente da versão 7.x do framework.

Testes rápidos

Chame um handler registrado por sua chave na URL, passando suas props no body:

curl -X POST https://my-store.example.com/deco/invoke/vtex/loaders/intelligentSearch/productListingPage \
  -H "Content-Type: application/json" \
  -d '{ "query": "shoes", "count": 12 }'

A conta precisa estar configurada e o handler registrado. Confira também URLs reais de PDP, PLP, busca, cookies do carrinho e checkout; uma consulta de catálogo bem-sucedida não valida todo o storefront.

Pegadinhas de configuração

Separe configurações de conta/domínio da identidade pública do site. Verifique região e segmentos com visitantes representativos. Escolha sections e projection do carrinho conforme a UI; são opções independentes. Veja Cart v2 e hooks VTEX.

Veja também