A collection of reusable, battle-tested patterns and best practices for building fast, maintainable storefronts with Deco on TanStack Start, React, and VTEX.
Build an API-frugal, CMS-configurable VTEX minicart with React Query. Zero getOrCreateCart on page load, lazy orderForm creation, canonical Minicart shape, micro-skeletons, and toast-vs-drawer toggle.
Reference: montecarlo-tanstack
Optimize add-to-cart bandwidth from 97 KB → 0.3 KB by returning only essential data on add, deferring full cart hydration to drawer-open intent.
Benefit: ~99.7% bandwidth reduction, no duplicate cart fetches.
Critical migration gotcha: reading signal.value in render doesn't re-render in React. Use useSignalValue hook instead.
Symptom: Drawer/modal doesn't open on click, but analytics logs fire.
Implement fine-grained loading states per line/section using pulse-in-place (not fixed boxes) to preserve exact dimensions and avoid CLS violations.
Pattern: Disable the real widget, don't hide it.
Combine HTML prefetch-on-hover (nav links, using bagaggio/instant.page) with SPA Link wrapper prefetch (product cards) for perceived performance gains.
Benefit: Category pages prefetch on nav hover; PDPs prefetch on card hover.
- Pick a skill relevant to your use case.
- Read the full skill document for context, gotchas, and trade-offs.
- Copy the reference implementation patterns into your project.
- Follow the verification checklist to validate the integration.
All skills are tested in production at:
- montecarlo-tanstack — TanStack Start + React + VTEX, Deco framework
Found a gotcha not documented here? Have a better pattern? Open a PR or discussion — these skills are living docs.