How to choose between headless and storefront

Introduction

Migrating your business or launching a new store on Shopware 6 comes with a crucial architectural decision: should you use the traditional Twig-based Storefront or go the modern headless route using APIs and your own frontend stack like Vue.js or React?

This isn’t just a developer decision. It affects:

• Time-to-market
• Frontend design freedom
• Ongoing maintenance effort
• SEO effectiveness
• Integration flexibility

This guide will walk you through technical, business, and operational perspectives on both options. By the end, you’ll have clarity on:

• Which approach suits your current needs
• How to assess your team and infrastructure for the future
• Risks and benefits of each option
• Realistic implementation scenarios

Whether you’re an agency, startup, or enterprise-level merchant, this guide is designed to help you make data-driven, strategic decisions before development begins.

1. Understanding Shopware 6 Architecture

To decide between Storefront and headless, first understand how Shopware 6 is structured:

1.1 Shopware Core & APIs

At the heart of Shopware 6 lies a powerful and flexible API-first architecture, designed to be modular, scalable, and technology-agnostic. This means that nearly every part of the system—whether it’s products, customer data, orders, or content—can be managed and accessed via APIs. This fundamental design principle is what makes Shopware uniquely suited for both traditional and headless commerce implementations.

Shopware 6 exposes three primary APIs, each serving a distinct purpose:

Admin API

• Use Case: Synchronizing catalog data from an ERP system
• Example: Updating stock quantities from a warehouse management system
• Authentication: Requires OAuth-based admin credentials

Store-API

• Use Case: Building a PWA using Vue/Nuxt or React
• Features: Includes context tokens, language detection, customer sessions
• Stateless: Built for fast responses and cacheability

This API is used even by the default Twig-based Storefront. So, even the traditional Storefront is technically “headless-friendly” under the hood.

Sync API

• Use Case: Importing 50,000 products with translations, media, and prices
• Structure: Accepts large nested JSON payloads
• Efficiency: Much faster than calling individual Admin API endpoints

Decoupled by Design

Because of these well-separated APIs, Shopware allows for any kind of frontend—whether it’s the classic Twig templates, a fully custom Nuxt SPA, a React-based storefront, or even a native mobile app—to interface with the backend cleanly.

This architecture also means:

• Frontend and backend can scale independently
• Teams can develop frontend and backend in parallel
• You can swap out frontends without refactoring the backend
• Multichannel and headless commerce becomes a default capability—not an add-on

1.2 Storefront (Twig-based Monolith)

The default Shopware 6 Storefront is a traditional, tightly integrated presentation layer built using the Twig templating engine, which is part of the Symfony ecosystem. It forms part of the monolithic Shopware application, meaning both frontend and backend are bundled together in the same project and deployed as a single unit.

This Storefront renders HTML server-side using predefined Twig templates for all critical eCommerce flows such as:

• Homepage
• Product listing and detail pages
• Shopping cart and checkout
• Customer account area
• CMS pages

All rendering, routing, and asset handling are managed within Shopware using its Page Loader System.

Theme and Plugin Support

The storefront supports:

• Theming via Twig inheritance and SCSS overrides
• Extensibility through Storefront plugins
• Custom JavaScript logic with Stimulus and Shopware’s asset pipeline

Themes can override Twig blocks, extend layout logic, or even define new CMS blocks using Twig partials. For example, a custom product badge or a new homepage slider can be added using standard frontend development practices.

Plugins also integrate tightly by injecting Twig templates, assets, or modifying services within the Symfony container. This architecture encourages consistent structure and plugin compatibility.

Pros

1. Quick setup and development
   No need to build a frontend from scratch. You can install Shopware, choose a theme, and begin selling within days.
2. Simplified deployment
   Since both frontend and backend live in the same codebase, a single deployment handles everything. No need for CI/CD pipelines per frontend/backend.
3. Broad plugin compatibility
   Most plugins from the Shopware Store are made for the Storefront. You benefit from features like advanced search, reviews, payment methods, or SEO enhancements without extra work.
4. Mature CMS support
   The Page Builder is deeply tied to Twig views. Editors can configure layouts, blocks, images, and call-to-action buttons visually, with no frontend intervention.

Cons

1. Limited flexibility in design tools
   Modern JS frameworks like Vue or React aren’t used here. You’re restricted to Twig templating, which is less flexible when building interactive UIs or dynamic animations.
2. Slower iteration for frontend-heavy projects
   Because the frontend is coupled with backend releases, changes to UI may require custom plugins or template overrides. You can’t experiment as freely with new layouts or page transitions.
3. Less suited for omnichannel delivery
   If you want to serve your store through a mobile app, a kiosk, or other channels, you’ll need to either extract Store-API data or rebuild those endpoints yourself.
4. SEO flexibility is limited to what’s built in
   While Shopware offers strong SEO features, more complex use cases—like international SEO, prerendering, or advanced schema support—may require plugin extensions or manual changes.

1.3 Headless (Composable Frontends)

In a headless setup, the frontend and backend are fully decoupled. The presentation layer is built outside of Shopware, and all business logic, product data, checkout flows, and CMS content are accessed through the Store-API.

This enables frontends in:

• Vue.js (Nuxt 3)
• React (Next.js)
• Svelte, Astro, Angular

Instead of relying on Twig templates rendered on the server, a headless frontend fetches data asynchronously and renders it in the browser (client-side), on the server (SSR), or even statically (SSG).

Key Benefits of Headless

Full UI/UX Control

You’re no longer bound by the constraints of Twig templating or legacy CSS frameworks. With headless, you can:

• Build immersive shopping experiences with animations, transitions, 3D product views
• Use your own design system or component library
• Customize every detail of layout and interactivity

Cutting-Edge Performance Techniques

Headless frontends allow you to implement modern performance strategies like:

• SSR (Server Side Rendering): For fast, SEO-friendly pages
• ISR (Incremental Static Regeneration): Blend speed and freshness
• Static Site Generation (SSG): Lightning-fast performance for rarely changing pages
• Edge Caching/CDNs: Distribute your store globally via Vercel, Netlify, or Cloudflare

These techniques can drastically reduce Time to First Byte (TTFB) and improve Lighthouse scores, which impact both SEO and user experience.

Scalable by Design

Headless architecture separates concerns. As a result:

• Your frontend and backend can be deployed and scaled independently
• You can cache frontend pages while Shopware handles order processing and admin tasks
• You can run different frontends for different regions or devices (e.g., mobile PWA, in-store kiosk)

Technical Considerations

In headless setups, you’ll need to manually implement:

• Cart and checkout logic using Store-API endpoints like /store-api/checkout/cart and /store-api/checkout/order
• Authentication and session handling, including login, token refresh, and persistent cart
• CMS rendering by mapping API-provided slot structures to frontend components
• Product filters, sorting, and pagination
• Example: Instead of {% for product in listing.products %} in Twig, you’ll fetch product data with an API call:
  
  

  const products = await $storeApi.get('/store-api/product', {
  
  params: {
  
  limit: 20,
  
  page: 1,
  
  filter: [...] 
  
  } 
  
  });

This adds flexibility but requires frontline engineering expertise and careful planning.

Business Use Cases for Headless

• Global brands wanting to localize UX for each market
• High-performance shops focused on SEO, speed, and mobile experience
• Content-heavy brands using headless CMS (e.g., Storyblok, Contentful)

Developer Workflow in Headless

Your team will typically:

• Use Nuxt/Next as the framework
• Fetch data from Shopware via Store-API (REST)
• Host the frontend separately on platforms like Vercel, Netlify, or AWS
• Implement CI/CD pipelines to automate builds and deployments

You’ll also manage environment variables, tokens, Store-API endpoints, error handling, and security from the frontend side.

2. Storefront vs Headless: A Deep Comparison

2.1 Architecture

The Storefront is tightly coupled—Shopware renders HTML directly using Twig on the server, meaning one unified project.

Headless, on the other hand, separates concerns. The backend exposes APIs, and your frontend consumes them to render pages independently. This means:

• You can deploy the frontend separately (e.g., on Vercel or Netlify)
• You can reuse the API for mobile apps or other devices
• You gain flexibility but lose some built-in convenience

For example, in a headless setup, the “Add to Cart” logic must be built in Vue or React, using Shopware’s Store-API. In Storefront, that’s already wired up using Symfony controllers and Twig.

2.2 CMS Handling

One of the most important architectural differences between Shopware’s Storefront and Headless approaches lies in how they handle CMS (Content Management System) features—especially layouts, landing pages, and custom content blocks.

Storefront CMS Integration

In the default Storefront, Shopware’s CMS is deeply integrated. Merchants and marketers can visually build layouts through a WYSIWYG editor inside the Shopware Admin. They can add blocks such as:

• Product Sliders
• Text + image combos
• Embedded videos or banners
• Forms, call-to-actions, or dynamic listings

Each of these CMS blocks is tied to a Twig template, which means:

• No frontend coding is needed to render CMS content
• Layout updates are previewable instantly
• SEO-friendly URLs are automatically handled
• Responsive behavior is managed via the theme’s grid system

Example: A marketing team can build a new landing page for a promotion using only drag-and-drop blocks—no developer required. That page is immediately available at a clean URL like /summer-sale.

CMS in Headless Frontends

In a headless architecture, the CMS is still accessible—but via the Store-API. A headless frontend (e.g. built with Vue/Nuxt or React/Next.js) must fetch CMS content from an endpoint such as:
/store-api/v3/cms-page/<page-id or page-key>

This API returns a structured JSON object that includes:

• The page layout (sections and blocks)
• Slot configurations
• Data for each CMS block (e.g., text, media, product list config)

Key Difference:The frontend must manually parse this JSON and render each block using custom components. You may need to create a Vue component for each CMS block type (e.g., TextBlock.vue, ImageBanner.vue, ProductSlider.vue).

Benefits for Storefront CMS

Feature	Description
Visual Editor in Admin	Content editors can build and edit pages without touching code.
Predefined Block Library	Many common layouts are already available and styled.
Instant Preview Support	Pages appear exactly as they will to end-users.
Automatic SEO URLs	Each page is crawlable and optimized.
No Developer Required	Marketing can act independently.

This is ideal for teams where non-technical users frequently need to create or update content.

Developer Considerations in Headless

• Use composables or hooks (e.g., useCmsPage) to fetch and normalize CMS content
• Build a dynamic layout renderer that loops over CMS sections and blocks
• Leverage a consistent design system to visually match Storefront-style blocks
• Optional: Add a live preview via an iframe that renders the Nuxt/React frontend with CMS page props

Best of Both Worlds?

Some projects combine Storefront CMS with headless rendering. For example:

• Use Storefront to manage marketing pages and CMS content
• Use a headless frontend (Nuxt) only for high-performance product detail pages or cart

This hybrid strategy offers CMS ease-of-use and frontend flexibility where it matters most.

2.3 Developer Tooling & Workflow

The developer experience varies significantly between Shopware’s native Storefront and a custom headless implementation. Both offer powerful tools—but the scope, responsibilities, and technologies differ greatly.

Let’s break down what developers typically deal with in each approach:

Storefront Developer Workflow

The default Storefront is built on Symfony, using Twig for templating, SCSS for styling, and Bootstrap as the UI framework.

• Templating: Twig templates render HTML server-side.
• Frontend assets: JS and SCSS are compiled via Webpack.
• Overrides: Themes and plugins can override templates using Twig block inheritance.
• Extensions: Plugins inject their own assets, JS, CSS, or modify layout blocks.
• Component behavior: JS functionality uses Shopware’s jQuery plugins and Stimulus-based modules.

Local development stack typically includes:

• ddev, docker or native setup
• Hot reloading for SCSS/JS via bin/webpack-dev-server
• Changes pushed via traditional deployments (e.g., rsync, FTP, GitLab CI)

Headless Developer Workflow

In a headless environment, developers typically use Nuxt 3 (Vue) or Next.js (React). The entire frontend stack is separate, often maintained in a dedicated Git repository.

• Templating: JSX (React) or Vue SFCs (Single File Components)
• Styling: Tailwind CSS, SCSS, or utility-first CSS frameworks
• Data fetching: Uses composables or hooks to call Shopware’s Store-API
• Routing & SEO: Handled manually or via framework plugins
• Previewing CMS data: Requires a dynamic page builder or slot renderer

Local development stack typically includes:

• Nuxt/Next CLI (npm run dev)
• Auto-imported APIs, asyncData functions, and middleware
• Deployed via CI/CD (GitHub Actions, Vercel, Netlify)

Challenges in Headless Tooling

• More moving parts: Backend and frontend must be managed independently
• Duplication of effort: Features like cart, login, and CMS rendering must be re-implemented
• Complex deployment: Separate CI/CD pipelines for both layers
• Code maintenance: Two teams may be required for long-term success

2.4 Performance

Performance is a mission-critical factor in modern eCommerce. It directly impacts:

• Conversion rates (slow sites lose sales)
• Search rankings (Google rewards fast-loading pages)
• Mobile user experience
• Infrastructure costs and scalability

The architecture you choose—Storefront (monolithic) vs. Headless (decoupled)—has major implications on how fast your site can become and how it behaves under load.

Why Headless Can Be Faster (If Done Right)

A properly optimized headless frontend allows you to leverage modern frontend performance strategies such as:

Static Site Generation (SSG)

• Pages are pre-rendered at build time and served as plain HTML.
• No real-time server processing—just fast CDN delivery.
• Ideal for high-traffic, low-update pages like home, category, or CMS landing pages.

Incremental Static Regeneration (ISR)

• Some frameworks (like Next.js or Nuxt 3 with Nitro) allow pages to be updated after deployment without a rebuild.
• Blends performance of SSG with flexibility of dynamic content.
• You can serve a cached page while the backend revalidates in the background.

Edge Caching & CDNs

• Deploy frontends globally using Vercel Edge, Netlify, Cloudflare Workers, or Akamai.
• Requests are fulfilled at edge nodes closest to the user.
• TTFB can drop below 100ms worldwide.

Lightweight Frontend Bundles

• Use lazy loading, tree shaking, code splitting.
• Only load components needed per page.
• Control exactly how and when assets are loaded.

Result: Your headless shop can feel like a native app—even on mobile.

Performance of Shopware’s Storefront (Monolithic)

The traditional Storefront is server-rendered, using:

• PHP & Symfony to execute business logic and fetch data
• Twig to render HTML on the fly
• Database reads to load content
• Symfony HTTP cache (e.g., via reverse proxy like Varnish or built-in HTTP cache)

While Shopware’s Storefront is reasonably fast and well-optimized, it has some inherent limits:

• Every page render requires PHP execution.
• Caching helps, but dynamic pages (cart, login, personalization) bypass cache.
• Scaling requires vertical or horizontal scaling of backend servers.

Example:
If 10,000 users hit a product listing page simultaneously:

• Headless (SSG): Served instantly from CDN
• Storefront: May require burst scaling of web servers or experience delays

Considerations & Pitfalls in Headless

Headless isn’t always faster by default. Mistakes in frontend implementation can actually make it worse:

• Poor API usage (e.g., N+1 calls for nested data)
• No prefetching or hydration strategies
• Large bundle sizes and blocking assets
• No SSR or fallback for crawlers

2.5 Plugin Ecosystem & Integrations

Most plugins in Shopware (e.g., Klarna, Reviews.io, Pickware) assume you’re using the Storefront. Their templates, JS assets, and styles are injected into Twig views.

In a headless setup:

• Plugins must offer API-first interfaces or webhooks
• Some plugins won’t work unless custom-integrated
• You’ll need to replicate UI manually (e.g., payment widgets)

3. Business Considerations

3.1 Budget Planning

Storefront costs less

• No need for dual hosting or multiple repos
• Fewer developers needed
• Fewer dependencies

Headless is more expensive up front:

• Requires frontend engineers
• DevOps to manage deployment pipelines
• More QA and testing layers

However, headless can pay off in the long run with improved performance, conversions, and reusability across channels.

3.2 Marketing Flexibility

Marketers benefit from:

• CMS previews
• Block configuration
• SEO URL management

These are baked into Storefront. In headless, these need to be integrated via custom UI or admin plugins.

Tradeoff: Headless gives more UX freedom but reduces CMS autonomy for non-devs.

3.3 Multi-channel Needs

Do you want to serve a:

• Website
• Mobile App (via API)
• Smartwatch or In-store Kiosk?

Headless makes this seamless.

4. When to Choose Storefront

Storefront is perfect when:

• You’re launching an MVP in < 8 weeks
• You have no in-house JS developers
• SEO is critical
• Plugin ecosystem is a must

Examples:

• Local brands
• Fashion stores
• B2B projects using existing plugins

5. When to Choose Headless

Choose headless when:

• You need apps, kiosks, mobile support
• You want animation-heavy or PWA interfaces
• You care deeply about TTFB and performance
• Your frontend team is skilled in Vue, React, Nuxt, etc.

Use cases:

• Global D2C brands
• Subscription services with custom UX
• Shopify-to-Shopware migrations wanting full design overhaul

6. Hybrid Models

Instead of choosing one approach, you can combine them:

Page Type	Storefront or Headless
Home Page	Headless
Product Listing	Headless
Checkout	Storefront
Account Area	Storefront

Benefits:

• Reduced risk
• Easier testing of headless performance
• Gradual migration path

7. Shopware Frontends

Shopware’s official headless frontend is:

• Built in Vue 3 + Nuxt 3
• Uses Store-API under the hood
• Provides authentication, cart, CMS, and checkout as Vue composables

Shopware Frontend drastically reduces boilerplate for frontend developers—no need to reinvent the wheel.

8. Risks & Challenges

Risk	Mitigation
Plugin incompatibility	API-first plugin audit
Higher cost	Start with hybrid rollout
SEO risks	Implement SSR or prerendering
Increased complexity	Use Nuxt with templates and middleware
Slower time-to-market	Build in parallel with backend dev

9. Case Studies

Brand Name	Architecture	Reason Chosen
Pickware	Storefront	Needed rapid MVP with full plugin stack
BITBAG.io	Headless	Complex integrations, multilingual PWA
Enterprise D2C	Headless	Omnichannel + external CMS
Local Grocer	Storefront	Budget-focused launch

10. Migration Path

Path from Storefront to Headless:

1. Start with Storefront for MVP
2. Rebuild homepage in Vue/Nuxt
3. Add CMS support
4. Migrate product pages
5. Replace checkout & cart
6. Retire Storefront entirely

11. Final Decision Checklist

• Do you need omnichannel or app delivery? → Headless
• Is your team familiar with Vue/React? → Headless
• Do you rely on plugins like Reviews.io or Klarna? → Storefront
• Is SEO a priority with fast launch? → Storefront
• Do you want full UI/UX freedom? → Headless

12. Conclusion

There’s no universal answer—just the right fit for your business goals, technical stack, and user experience priorities

Shopware 6 gives you the flexibility to start simple and evolve over time. Whether you launch with Twig or dive into a full Nuxt-powered PWA, this guide should help you choose with clarity and confidence.

Tip: Start small. Test. Measure. Scale. That’s the beauty of Shopware’s modular API-first foundation.