Skip to main content
Shopware’s default storefront renders the Frontic Experience element out of the box, because the Frontic plugin ships its template. A headless storefront renders Shopping Experiences with its own components, so it needs one more: a component for the frontic-experience element. You build it once. Every experience your team publishes afterwards goes through it, with no further deploy. This page is for storefronts that already render Shopware’s Shopping Experiences from the Store API - with Shopware Frontends, or with a CMS renderer of your own in Nuxt or Next.js. If you’d rather hand the work to a coding agent, start with the agent prompt; the rest of the page explains what it builds.
Creating and publishing an experience works the same as for the default storefront - see Frontic Experiences in Shopware. Only the rendering on your storefront is yours to add.

Agent prompt

Paste this into the coding agent you use on your storefront’s repository. It carries the whole contract, so the agent doesn’t need this page open.

Have your coding agent add the Frontic Experience element to a headless Shopware storefront

Before you start

  • Frontic plugin 1.1.1 or newer. Older versions return the element without its markup over the Store API.
  • A real domain on the sales channel. An experience that shows the page’s own category or product - see Experiences on category and product pages - is rendered per request, for the sales channel’s domain in the request’s language. The sales channel your storefront’s access key belongs to needs a domain with an http or https URL for each language you serve. A placeholder such as default.headless0 doesn’t count.

What the Store API returns

The plugin registers one block and one element, both of type frontic-experience. The block has a single slot named content, which holds the element. In a CMS page response the element carries the finished markup in data:
Shopware resolves everything else on its side: the language of the request, and for a per-request experience the render itself. Your storefront never talks to Frontic for this.

The markup to render

Whatever the framework, the component produces this:
Three things matter here:
  • The shadow root. An experience brings its own styles and expects to be isolated from yours. Mounted into the light DOM, its CSS leaks into your page and your CSS leaks into it.
  • The class names and data-frontic-slot-id. They match the default storefront, and the Designer uses them to find the slot when it previews an experience on your storefront. data-frontic-record is kind:key from data.record, and is left out when there is no record.
  • Scripts have to run. An interactive experience carries its scripts inline. A browser runs them when it parses a server-rendered page. After a client-side navigation the markup arrives through innerHTML, which leaves both the <template> and the scripts inert, so the component attaches the shadow root itself and re-creates each script.

Build the element

1

Add the shared helper

One framework-free file holds the element’s type and the browser-side mount.
frontic-experience.ts
On a server-rendered page the browser has already turned the template into a shadow root and run its scripts, so mountExperience finds no template and does nothing.
2

Add the component

Keep the helper in utils/, so Nuxt imports it for you.
components/cms/CmsElementFronticExperience.vue
3

Register it with your CMS renderer

The last step tells your storefront that frontic-experience maps to the new component.
Shopware Frontends resolves CMS components by name, block and element separately. The element component above already has the right name, CmsElementFronticExperience. Add the block next to it, and register both globally, like every custom CMS element.
components/cms/CmsBlockFronticExperience.vue
nuxt.config.ts
4

Check it

Publish an experience into a layout, then open the page on your storefront twice: once by loading its URL directly, and once by navigating to it from another page. Both have to show the experience, with working interactions. If only the direct load works, the client-side mount is missing.

Good to know

  • Load category and product pages through their own routes. A per-request experience needs to know which category or product the page shows. Shopware only knows that on the Store API’s category and product routes. Loaded as a bare CMS page by its ID, the element comes back with empty markup.
  • Add to Cart doesn’t reach a headless cart yet. Add to Cart buttons inside an experience talk to the default storefront’s cart. On a headless storefront they have no cart to add to. Until that changes, leave cart actions out of experiences for a headless storefront, and link to the product page instead.
  • Links are plain links. Product and category links inside an experience are root-relative Shopware SEO paths. They work as full page loads. To route them through your framework, listen for clicks on the host element - a click that starts inside a shadow root only shows its link in event.composedPath().
  • The markup is trusted. It comes from your own Shopware instance, and it’s mounted as is, scripts included - the same trust Shopware’s HTML element asks for.
  • One language per response. Shopware returns the markup for the language of the Store API request. A language the experience wasn’t built in gets its primary language.

Shopware connector

Installing the plugin, and creating an experience from a Shopping Experience layout.

Publishing

Versions, going live, and rolling back an experience.

Building an experience

The canvas, stages, and Designer settings.

Experience Designer

What experiences are and how to create one.