Skip to content
decodecodeveloper docs
Storefront → Templates → Commerce

VTEX overview

Connect a released Blocks 7.x storefront to VTEX with registered provider modules.

The VTEX app supplies server-side catalog, search, cart, account, and session integrations, plus supported React hooks. This guide targets Blocks 7.x; use the versioned VTEX reference for its complete runtime contract.

What you need

Use your VTEX account and supported API credentials. The website supplies the UI; the app integrates the provider; the Site Editor changes saved app configuration.

Configuration block

Save the account and public storefront URL:

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

Autoconfiguration resolves appKey and appToken from encrypted values or the VTEX_APP_KEY / VTEX_APP_TOKEN server environment fallbacks. The pair is sent only when both are configured. country uses an ISO alpha-3 code such as BRA; salesChannel remains a deprecated legacy default, not a replacement for per-visitor segment handling.

Wiring at setup time

Register the provider after framework setup has loaded the decofile. Import this module from the server's Worker entry after ./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 takes both the blocks map and a site-composed registry. If using initVtexFromBlocks(blocks) instead, pass the map supplied by initPlatform and note that the convenience initializer only accepts plain-text credentials.

Register commerce loaders

For cached, CMS-shaped product and listing loaders:

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

Instrument the provider

Configure its resilient, instrumented fetch once in server setup:

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

Middleware

On TanStack, wire segment-aware caching, checkout proxy, and sitemap proxy through the Worker entry. Use the concrete Worker wiring example, rather than treating provider helper functions as TanStack middleware factories. The Next.js binding has a different request contract.

What you get

Registered loaders and actions, app configuration, supported cart/user/wishlist hooks, and provider-specific request behavior. Code must register these before the Site Editor can expose their schemas. Cart v2 names the cart contract, independently of the framework's 7.x version.

Quick smoke tests

Call a registered handler by its URL key, with its props as the 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 }'

The account must be configured and the provider handler registered. Also verify real PDP, PLP, search, cart cookies, and checkout URLs; a successful catalogue request alone is not a storefront acceptance test.

Common configuration mistakes

Keep account/domain settings separate from the public storefront identity. Verify region and segment propagation with representative visitors. Choose cart sections and projection for the UI's needs; these are independent options. See Cart v2 and VTEX hooks.

See also