How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/decocms/blocks --skill apps-vtexBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
@decocms/apps-vtex
The VTEX integration as a framework-agnostic package (port of deco-cx/apps vtex/, formerly the vtex/ folder of @decocms/apps-start). Source: packages/apps-vtex/src/. client.ts is the HTTP layer — vtexFetch, vtexFetchWithCookies (forwards the browser Cookie and pushes upstream Set-Cookie into RequestContext), vtexCachedFetch / intelligentSearch (SWR cache via utils/fetchCache.ts), vtexIOGraphQL. actions/ holds the mutations (checkout.ts incl. the Cart v2 *V2 actions, auth, session, profile, wishlist, masterData…), loaders/ the reads (catalog, intelligentSearch/, legacy/, cart/ for Cart v2, workflow/, minicart…), hooks/ the client hooks (legacy useCart/createUseCart, useUser, useWishlist, Cart v2 createCart and cartQuery), utils/ the shared pieces (transform.ts schema.org mapping, vtexId.ts, segment.ts, constants.ts + resilience.ts + instrumentedFetch.ts, simulationCache.ts). middleware.ts extracts VTEX request context and IS cookies; invoke.ts declares the actions blocks-cli's generate-invoke turns into server functions. Public entry points are the package.json exports map (./client, ./actions/*, ./loaders/*, ./hooks/*, ./utils/*, ./inline-loaders/* aliases…).
When to load what
| Symptom / task | Load |
|---|---|
Cart empties after add-to-cart, /checkout opens a fresh order, only one comma-joined Set-Cookie in DevTools | `audit-cookie-propagation.md` |
Logged-in call 401/403, hardcoded VtexIdclientAutCookie, client reading the HttpOnly auth cookie | `audit-auth-cookies.md` |
OrderForm missing totals/shipping/etc. (expectedOrderFormSections) | `audit-expected-order-form-sections.md` |
Wrong prices, ORD027, products invisible for a sales channel (sc) | `audit-sales-channel.md` |
Intelligent Search results/personalization off (vtex_is_session) | `audit-intelligent-search-cookies.md` |
Checking hooks / transform.ts / PDP-PLP shapes against deco-cx/apps | `audit-deco-cx-apps-parity.md` |
| Reviewing an apps-vtex PR or porting code — file map, full checklist, validation greps | `audit-checklist.md` |
| Building a minicart / badge / add-to-cart, cutting cart traffic, why Cart v2 exists | `cart-overview.md` |
Choosing a projection or sections preset | `cart-contract.md` |
Reading cart data: cart/summary, full, shipping, gifts, attachments | `cart-loaders.md` |
Calling the *V2 mutations directly | `cart-actions.md` |
Using createCart hooks (useCartSummary, useAddToCart, useCart, …) | `cart-hooks.md` |
Site already on @tanstack/react-query — createCartQuery | `cart-react-query-adapter.md` |
invoke.vtex.actions.*V2 / invoke.vtex.loaders.cart.* missing in a site | `cart-wiring.md` |
Moving a live site off legacy useCart/createUseCart | `cart-migrating-from-legacy.md` |
| Stale VTEX responses, adding cache to a VTEX endpoint, cache tuning knobs | `fetch-cache.md` |
Generic SWR / createFetchCache / edge-cache mechanics are not VTEX-specific — see the deco-caching skill.
Invariants worth knowing before you open a reference
- Anything that mutates cart/session/auth goes through
vtexFetchWithCookies, nevervtexFetch/vtexCachedFetch— the cached path dropsSet-Cookieand the cart drifts from VTEX. Set-Cookieis copied onto the HTTP response withHeaders.getSetCookie(), neverentries()/forEach(they collapse N cookies into one the browser discards).- The
VtexIdclientAutCookieconstant lives inutils/vtexId.ts;utils/cookieSanitizer.ts(forwarding allowlist),utils/cookies.tsandutils/authHelpers.ts(parsers) also match the name — change them together. It is HttpOnly, so auth status comes from/api/sessions, notdocument.cookie. - Only cache responses that are identical for every shopper given the URL.
