Headless Architecture on VTEX: Options and Trade-offs
VTEX has evolved from a monolith with its own CMS to a platform that supports and encourages headless architectures. Today, the VTEX backend (catalog, checkout, OMS, pricing, logistics) can be consumed by any frontend via well-documented APIs. But which frontend to choose? FastStore (the official solution), deco.cx (maximum edge performance), or a custom Next.js project (total freedom)? Each path has its trade-offs in performance, cost, time-to-market and maintenance. This article analyzes each option in depth, based on real implementation experience, to help you decide what makes sense for your operation.
Current state: Store Framework vs headless
Store Framework (React blocks on VTEX IO) is still the most adopted option in the VTEX ecosystem. It is mature, has an extensive app marketplace and allows building stores without writing much custom React code. But it has structural performance problems: the JavaScript bundle is heavy (frequently 500KB+), hydration is complete (the entire page is hydrated even though 90% is static), and each installed app adds bundle weight. The result is Lighthouse scores typically between 30-60, LCP of 4-6 seconds and INP of 300-500ms. For operations where performance is priority, Store Framework has reached its limit. VTEX acknowledges this and directs new projects toward FastStore or headless architectures. Store Framework will continue to be supported, but VTEX's investment is elsewhere.
FastStore: the official option
FastStore is VTEX's official headless framework, built on Next.js with Tailwind CSS. It uses VTEX Intelligent Search and VTEX Checkout natively. VTEX offers starter kits, dedicated documentation and priority support for FastStore projects. Performance: consistent Lighthouse 85-95, LCP of 1.5-2.5 seconds, TTFB of 100-300ms. It is significantly better than Store Framework, but does not reach deco.cx's edge computing level. Advantages: official VTEX support, native ecosystem integration (Intelligent Search, Checkout, My Account), starter kit that accelerates development, specific documentation and dedicated support channel. Disadvantages: inferior performance compared to edge solutions, Next.js ecosystem dependency (long build times, server-side rendering on origin server), less visual editor flexibility compared to deco.cx, and pre-built components that may limit deep customizations. Recommended for: VTEX operations wanting headless without leaving the official ecosystem, teams already familiar with Next.js, and projects valuing platform support over maximum performance.
deco.cx with VTEX backend
deco.cx works as a headless frontend consuming VTEX APIs. Catalog, pricing, inventory, checkout and logistics remain on VTEX. deco.cx handles only the presentation layer and renders on the edge. Performance: Lighthouse 92-100, LCP below 1 second, TTFB of 30-80ms. It is the most performant option for VTEX operations. VTEX integration is mature: pre-built loaders for catalog, search, PLP, PDP, cart and checkout redirect. The business team edits pages through deco.cx's visual panel while data comes from VTEX. Advantages: unmatched edge performance, complete visual editor, works with any backend (can keep VTEX now and migrate in the future), islands architecture for minimal hydration. Disadvantages: Fresh/Deno ecosystem less familiar to React devs, platform license, less native integration with VTEX-specific features (e.g., admin extensions), dependency on a third-party company for the frontend. Recommended for: operations where performance is priority number 1, stores with high mobile traffic, teams willing to invest in the Fresh/Deno learning curve.
Custom Next.js with VTEX APIs
The third option is building a Next.js frontend from scratch consuming VTEX APIs directly. No opinionated framework, no starter kit, with total control over every technical decision. Performance: depends entirely on implementation. A well-built Next.js with ISR, edge middleware and optimizations reaches Lighthouse 80-95. A poorly implemented Next.js can be as slow as Store Framework. Advantages: absolute technical freedom, enormous React/Next.js ecosystem, hiring Next.js developers is easy, no frontend platform dependency, deploy on any provider (Vercel, Cloudflare, AWS). Disadvantages: development cost 3-5x higher than using an opinionated framework, all integrations need to be built from scratch, no out-of-the-box visual editor (need to integrate a CMS like Sanity or Contentful), maintenance entirely the team's responsibility, risk of reimplementing problems already solved by frameworks like FastStore and deco.cx. Recommended for: operations with strong dedicated technical teams, projects with very specific needs no opinionated framework addresses, companies wanting no frontend platform dependency.
Checkout: keep native or rebuild?
Checkout is the most critical point of any e-commerce. It is where money happens. The decision to keep native VTEX checkout or rebuild headless should be made with extreme care. Arguments for keeping native checkout: it is conversion-optimized with years of iteration, PCI DSS certified, supports all configured payment methods, Smart Checkout V6 has acceptable performance, security responsibility lies with VTEX. Arguments for headless checkout: visually consistent experience with the rest of the site, possibility of UX-specific optimizations, removal of unnecessary elements, custom one-page checkout. In practice, 90% of headless operations on VTEX keep native checkout. The cost of rebuilding a secure, tested and certified checkout rarely justifies itself. The pattern is: the headless frontend builds the cart via API, and at checkout moment redirects to VTEX SmartCheckout with minimally adapted visuals via CSS/JS customization. The user does not notice the transition when well implemented.
Real migration patterns
Based on real projects, the most common migration patterns from Store Framework to headless on VTEX are: Gradual migration (strangler fig): start with homepage and landing pages in headless, keep PLPs, PDPs and checkout on Store Framework. Validate performance and conversion. Migrate PLPs next, then PDPs. Lastly, evaluate checkout. Total time: 3-6 months in incremental sprints. Complete migration (big bang): rebuild the entire frontend at once and go-live on a specific date. Riskier but faster (6-10 weeks of intense development). Works better with experienced teams and stores with controlled scope. Permanent hybrid: keep content pages (blog, landing pages, institutional) in headless and transactional pages (PLP, PDP, checkout) on Store Framework. Accept that not everything needs to be headless. This pattern is surprisingly common and works well for operations wanting performance on top-of-funnel pages without risking the transactional flow.
Final decision: how to choose
The decision between FastStore, deco.cx and custom Next.js depends on three factors: required performance, business team autonomy and cost the operation accepts. If maximum performance is priority and the team accepts the Fresh/Deno curve: deco.cx. If you want headless within the official VTEX ecosystem with platform support: FastStore. If you need total freedom and have a strong technical team: custom Next.js. If Store Framework works and performance is not a bottleneck: do not migrate. The worst decision is migrating to headless out of hype without real need. Headless adds complexity. If Store Framework works, optimize it (remove unnecessary apps, implement lazy loading, use GraphQL cache) before considering a complete rebuild.